Difference between revisions of "Coding-tutorial"

From The Powder Toy
Jump to: navigation, search
(Optional: Defining the Element Without Running generator.py)
m (Reverted edits by JohnLolFun (talk) to last revision by LBPHacker)
 
(30 intermediate revisions by 12 users not shown)
Line 1: Line 1:
This tutorial is in progress (not finished)
+
{{Languages|Coding-tutorial}}
 
 
 
 
This tutorial will give you guidelines on creating an element in The Powder Toy. We will use triclops200's heater element in this example. The color will be the same as the HEAT element, and it will be an indestructible solid in the special menu, that transfers heat quickly. Updated to latest source by cracker64 (and now again by jacob1), if you have any problems please post a thread on the [https://powdertoy.co.uk/Discussions/Categories/Topics.html?Category=5 forums]
 
  
 +
'''ATTENTION: This guide is severely out of date as of 2021. Disregard everything you see below this notice. This should be fixed soon. Until then, the quick and informal one-sentence tutorial is as follows: successfully compile TPT first [[Building TPT with Meson|following this guide]], then create a new element file in src/simulation/elements based on other element files in the same directory, add it to the list in src/simulation/elements/meson.build, then recompile.'''
  
 +
This tutorial will give you guidelines on creating an element in The Powder Toy. We will use the heater (HETR) element in this example, which you can find [https://drive.google.com/uc?id=0B1XWtCTn2YPAUTl2WTFMRG9lYWs&export=download here]. The color will be the same as the HEAT element, and it will be an indestructible solid in the special menu, that transfers heat quickly. If you have any problems please post a thread on the [https://powdertoy.co.uk/Discussions/Categories/Topics.html?Category=5 forums]
  
 
It's not as simple as typing the name, color, and features, but it's almost that easy.  
 
It's not as simple as typing the name, color, and features, but it's almost that easy.  
 
 
 
With tpt++, it is now much easier to create new elements, without needing to add extra lines to powder.h. Everything is done in the one new element file now.
 
 
 
  
 
== Part One: Defining the Element's Properties ==
 
== Part One: Defining the Element's Properties ==
Line 18: Line 11:
 
=== Step One: Defining the Element ===
 
=== Step One: Defining the Element ===
  
Create a new element file, (HETR.cpp for this example, or whatever name your element will be) inside of src/simulation/elements. (or, i'll probably have people download [https://dl.dropbox.com/u/43784416/PowderToy/HETR.cpp mine] when this guide is finished)
+
Create a new element file, (HETR.cpp for this example, or whatever name your element will be) inside of src/simulation/elements.
  
Open ElementClasses.h in the editor of your choice (Visual Studio for windows users) and find the first open id. This is whatever number comes after the long list of #define PT_XXXX. Remember this for later, in the future this step will probably not be needed.
+
After you put this into the /elements folder, you have to add it to the solution.
You do not need to edit ElementClasses.h yourself anymore, this file is generated automatically when generator.py is ran. If you use visual studio, you have to run this file manually every time you make a new element. The Visual Studio compiling guide should have told you to do this.
 
  
 +
1.  Open up your solution file, then go to the Solution Explorer pane. 
  
=== Optional: Defining the Element Without Running generator.py ===
+
2. Go to src/simulation/elements/
  
After creating your new element file, go into ElementClasses.h and find the first open space after the last #define PT_XXXX yyy.
+
4. Right click the 'elements' folder
Add your new element in the same format; if the element is HETR, add a new line with #define PT_HETR yyy. yyy is the numerical value of your element. Just set that value to the next greater one of the line above. Example of what this should look <nowiki>like after adding HETR:
 
#define PT_FRME 169
 
#define PT_GOLD 170
 
#define PT_TUNG 171
 
#define PT_PSNS 172
 
#define PT_HETR 173</nowiki>
 
  
Next, go to the bottom of ElementClasses.h and add the following block of code:
+
5.  Go to Add -> Existing file
  
class Element_XXXX: public Element
+
6. Navigate to src/simulation/elements and double click your element file HETR.cpp
{
 
public:
 
Element_XXXX();
 
virtual ~Element_XXXX();
 
static int update(UPDATE_FUNC_ARGS);
 
static int graphics(GRAPHICS_FUNC_ARGS);
 
};
 
  
Change XXXX to your new element name.
+
Your new element should now be included in the solution!  If you don't do this, you will get errors when you try compiling your new mod.
static int update and graphics are giving your element the update and graphics functions that allow the element to look pretty(optional) and allow the element to be used how it is coded in its cpp file(needed).
 
If your element does not have any special graphics such as glowing colours or brightness, then you do not need
 
static int graphics(GRAPHICS_FUNC_ARGS);
 
  
Next, open ElementClasses.cpp and go to the last line, which will say something like "elements.push_back(Element_XXXX());".
+
Open ElementClasses.h in the editor of your choice (Visual Studio for windows users). ElementClasses.h is located under Source Files -> generated in the Solution Explorer. Double click it to open it up.
add the same line after that, but change XXXX to your element.
+
You will see a file that should have a big list of #define PT_XXXX Y. Scroll down until you reach the end of this list of statements that follow this format. Remember this number. You will need to enter a number greater than this one into the .cpp file you create for your new element. Currently, the largest element ID is LDTC, 186. Your element should have an ID of 187.
  
Now, make sure that your element's cpp file is in src/simulation/elements, and if it is not, put it there. Also, be sure that it is added to the project. You can add it by putting the file in the directory mentioned above, then right clicking on your project name/Source Files and choosing "Add existing Item". find your new element and add it. If you did everything above correctly, it is time to move on to coding the element itself.
+
You should not edit ElementClasses.h yourself, this file is generated automatically when generator.py is ran. It uses the "//#TPT-Directive" comments to do this, so make sure you have the element fully written before you run it. For Visual Studio you have to run generator.py manually every time you finish making a new element. The Visual Studio compiling guide should have given a good explanation.  If you didn't read that, then here is a short version:
  
=== Step Two: Defining the Element's Primary Properties ===
+
1.  Locate the folder where your source code is located.
  
Now, open up your new element file. It already has all the values filled in, but if you don't want to make HETR (you probably don't), you should edit them. There are descriptions for all of them inside the file, and some include examples of the ranges for the values. The descriptions are repeated here:
+
2. In this directory there should be a file named "generator.py"
  
{|
+
3. Double click it to run it. A black window should appear for a second or so, then disappear. This means that it worked. You can check to see if ElementClasses.h was updated to confirm.
! Property name || Function
 
|-
 
| '''Identifier'''|| Identifier string, used for lua and internal stuff. Formatted like DEFAULT_PT_XXXX
 
|-
 
| '''Name'''|| Name, it is recommended to use 4 letters, but less works. 5 or more will probably not fit on the buttons
 
|-
 
| '''Colour'''|| Default color, in hexadecimal (RRGGBB). In the deco editor, it will tell you the color in hex, ignore the initial FF, and use the 6 digits after for this
 
|-
 
| '''MenuVisible'''|| If it's visible in the menu, if 0 then it is hidden and can only be produced with reactions or lua
 
|-
 
| '''MenuSection'''|| The menu section it's in, see src/simulation/SimulationData.h for a list, but you can probably guess their names on your own
 
|-
 
| '''Enabled'''|| If 0, it cannot be created or seen in any way, not even lua. It will just disappear if somehow created. Used for removed elements, you should leave this 1
 
|-
 
| '''Advection'''|| How much the particle is accelerated by moving air. Normally 0 for solids, and up to 1 for other elements. It can be negative, ANAR and DEST do this so it goes towards pressure
 
|-
 
| '''AirDrag'''|| How much air the particle generates in the direction of travel. Generally is very small, 0.04f creates a lot of positive air (- creates negative pressure).
 
|-
 
| '''AirLoss'''|| How much the particle slows down moving air (although not as big an effect as a wall). 1 = no effect, 0 = maximum effect. Solids are generally above 0.90f, along with most other elements too
 
|-
 
| '''Loss'''|| How much velocity the particle loses each frame. 1 = no loss, .5 = half loss. Solids have it at 0. Only a few have it at 1, like energy particles, and old moving sponge.
 
|-
 
| '''Collision'''|| Velocity is multiplied by this when the particle collides with something. Energy particles have it at -0.99f, everything else is -0.01f or 0.0f. This property does not do much at all.
 
|-
 
| '''Gravity'''|| How fast the particle falls. A negative number means it floats. Generally very small, most gasses are negative, everything else is usually less than 0.04f
 
|-
 
| '''Diffusion'''|| How much the particle "wiggles" around (think GAS or HYGN). Set at 0, except for gasses, which is a positive number. Up to 3 (or higher) for a large amount of wiggle, GAS is 0.75f, HYGN is 3.00f
 
|-
 
| '''HotAir'''|| How much the particle increases the pressure by. Another property only for gasses, but VENT/VACU have theirs at (-)0.010f. An extremely small number, sometimes as small as 0.000001f
 
|-
 
| '''Falldown'''|| How does the particle move? 0 = solid, gas, or energy particle, 1 = powder, 2 = liquid.
 
|-
 
| '''Flammable'''|| Does it burn? 0 = no, higher numbers = higher "burnage". Something like 20 is WOOD, while C-4 is 1000. Some are a few thousand for almost instant burning.
 
|-
 
| '''Explosive'''|| Does it explode? 0 = no, 1 = when touching fire, 2 = when touching fire or when pressure > 2.5. Yes, those are the only options, see FIRE.cpp or somewhere in Simulation.cpp to modify how they work
 
|-
 
| '''Meltable'''|| Does it melt? 1 or higher = yes, 0 = no. This is actually only used when heat sim is off, to make it actually melt use element transitions
 
|-
 
| '''Hardness'''|| How much does acid affect it? 0 = no effect, higher numbers = higher effect. Generally goes up to about 50
 
|-
 
| '''Weight'''|| Heavier elements sink beneath lighter ones. 1 = Gas. 2 = Light, 98 = Heavy (liquids 0-49, powder 50-99). 100 = Solid. -1 is Neutrons and Photons
 
|-
 
| '''Temperature'''|| What temperature does it have when created? Temperature is in Kelvin (Kelvin = degrees C + 273.15). R_TEMP+273.15f gives room temperature
 
|-
 
| '''HeatConduct'''|| 0 - no heat transfer, 255 - maximum heat transfer speed
 
|-
 
| '''Description'''|| A short one sentence description of the element, shown when you mouse over it in-game
 
|-
 
| '''State'''|| What state is this element? Options are ST_NONE, ST_SOLID, ST_LIQUID, ST_GAS. Powders use solid, energy particles and some other random things use none
 
|-
 
| '''Properties'''|| Does this element have special properties? Properties are listed in src/simulation/Element.h, you at least need to have the correct state property. If you want it to conduct electricity, be sure to use both PROP_CONDUCTS and PROP_LIFE_DEC
 
|-
 
| '''Update'''||  The update function, todo: description
 
|-
 
| '''Graphics'''|| The graphics function, todo: description, + description of transitions too
 
|}
 
  
Properties:
+
=== Step Two: Defining the Element's Primary Properties ===
There are 5 properties for the different states:
 
  
<tt>TYPE_PART</tt>(powders), <tt>TYPE_LIQUID, TYPE_SOLID, TYPE_GAS</tt>, and <tt>TYPE_ENERGY</tt>. You should pick one of these to use for your element.
+
Now, open up your new element file. It is empty right now, it is recommended you copy from another element, or this template here: [https://drive.google.com/uc?id=0B1XWtCTn2YPAUTl2WTFMRG9lYWs&export=download HETR.cpp] . The file is entirely commented, you can just change the properties to how you want.
  
If your element conducts electricity, use <tt>PROP_CONDUCTS and PROP_LIFE_DEC.</tt>
+
Please look at the full list of Properties is here: [[Element_Properties]]
  
<tt>PROP_DEADLY</tt> makes your element kill stickmen.
+
This is a lot to handle, and if you feel overwhelmed by some of the choices, try looking at elements similar to what you are creating and copy the values from those.
  
<tt>PROP_HOT_GLOW</tt> makes your element glow when hot, like metl does.
+
=== Step Three: Defining the Element's State Changes ===
  
<tt>PROP_RADIOACTIVE</tt> makes your element radioactive.
+
In the linked property list page you will notice some special ones named LowPressure, LowPressureTransition, etc. These control all state changes for high/low pressure and temperature. It is very easy to edit these and add in transitions. Lets take GAS as an example. In GAS.cpp, you will find this:
 
+
<syntaxhighlight lang="c">
There are a few more properties, you can find out about them in src/simulation/Elements.h
+
LowPressure = IPL;
 
+
LowPressureTransition = NT;
This is a lot to handle, and if you feel overwhelmed by some of the choices, try looking at elements similar to what you are creating and base the value off of that. The following values are an example of what your code is supposed to look like. The color of heater will be the same as the HEAT element, and it will be an indestructible solid in the special menu that transfers heat quickly.
+
HighPressure = 6.0f;
 
+
HighPressureTransition = PT_OIL;
====END OF EDITING, THE REST BELOW IS OLD====
+
LowTemperature = ITL;
 
+
LowTemperatureTransition = NT;
<syntaxhighlight lang="c">
+
HighTemperature = 573.0f;
{"FIGH", PIXPACK(0x000000),    0.5f, 0.00f * CFDS,    0.2f,      1.0f, 0.0f,    0.0f,    0.0f, ...
+
HighTemperatureTransition = PT_FIRE;
{"HETR",    PIXPACK(0xFFBB00),    0.0f,    0.00f * CFDS,    0.90f,    0.00f,    0.0f,    0.0f,    0.00f,
 
0.000f  * CFDS,    0,    0,      0,  0,    0,    1,    1,    100,    SC_SPECIAL,        22.0f+273.15f,  251,
 
"Heats objects it touches", ST_SOLID, TYPE_SOLID, NULL, NULL},
 
};
 
</syntaxhighlight>
 
 
 
=== OLD: Step Three: Defining the Element's State Changes ===
 
 
 
In powder.h, ~line 828 (or at the end of elementdata.c) Find:
 
<syntaxhighlight lang="c">
 
//     if low pressure if high pressure if low temperature if high temperature
 
// Name     plv plt phv pht tlv tlt   thv tht
 
/* NONE */ {IPL, NT, IPH, NT, ITL, NT, ITH, NT},
 
/* DUST */ {IPL, NT, IPH, NT, ITL, NT, ITH, NT},
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
This part of the code is new as well, it replaces the old states table and replaces it with a transition table.  This means you will define when the element changes into another. For example WATR, it will freeze at 273.15K, so in this table it has a transition at a LOW temp of 273.15, and will turn into ICE. Similarly, water boils at 373, so it will have a transition at a HIGH temp of 373. Here is the line for WATR:
+
This makes it change into OIL at higher than 6.0 pressure, and change into FIRE at higher than 573.0K. Note that all temperatures are in Kelvin, so you have to subtract 273.15 to get the temperature in Celcius. In this case it transitions at 299.85C.
<syntaxhighlight lang="c">
 
/* WATR */ {IPL, NT, IPH, NT, 273.15f,PT_ICEI, 373.0f, PT_WTRV},
 
</syntaxhighlight>
 
  
This table now also has pressure transitions, such as ICE breaking into SNOW under pressure, this is done the same way, there is a LOW pressure change, and a HIGH pressure, here is the line for ICE:
+
For some transitions, there is one more step. If you want it to transition back, you need to add similar code into the other element. Lets say you wanted OIL to change back into GAS once it goes under 6.0 pressure again. You would need to go into OIL.cpp and change the pressure transitions to this:
 
<syntaxhighlight lang="c">
 
<syntaxhighlight lang="c">
/* ICE  */ {IPL, NT, 0.8f, PT_SNOW, ITL, NT, 233.0f, ST},
+
LowPressure = PT_GAS;
 +
LowPressureTransition = 6.0f;
 
</syntaxhighlight>
 
</syntaxhighlight>
 
As you can see, there is a HIGH pressure transition of 0.8, which means if the pressure goes above 0.8, then it will turn into SNOW.
 
  
 
NOTE: For an element that does NOT have a transition at high/low pressure/temp, please follow the same format as the others and use IPL,IPH,ITL,ITH and NT.
 
NOTE: For an element that does NOT have a transition at high/low pressure/temp, please follow the same format as the others and use IPL,IPH,ITL,ITH and NT.
  
lets add heater, this is simple because for our simple heater, it has no transitions, so everything should be IPL,IPH,ITL,ITH and NT.
+
HETR is very simple and has no transitions, so everything should be IPL,IPH,ITL,ITH and NT.
<syntaxhighlight lang="c">
 
    /* FIGH  */ {IPL, NT, IPH, NT, ITL, NT, ITH, NT},
 
    /* HETR  */ {IPL, NT, IPH, NT, ITL, NT, ITH, NT},
 
</syntaxhighlight>
 
 
 
  
=== Step Four: Defining the Element's Special Properties ===
+
=== Step Four: Defining initial values ===
  
At this point, you would be able to compile, and the HETR would show up in the menu and you can place it, BUT it doesn't do anything!  Now for the part where we actually code what the element does.  Make sure to save powder.h.
+
Some elements start off with certain properties by default, for example PHOT gets a .life value of 680.  
  
This is also where new element creation is different from before, if you look inside the src folder, you will now see an elements folder.  Inside here is a *.c file for each major element.
+
'''CURRENT VERSION OF TPT`
  
Now we need to make a hetr.c file for our new heater element, if using visual studio, you should be able to right click on the source folder inside the project, and create a new file, and name it hetr.c  Once you have a blank hetr.c created and it is included in the project, we need to add a few things to this file.
+
In the current version of TPT, you can directly modify a DefaultProperties variable. For example, if we wanted .tmp to start out as "1" for HETR, we can write anywhere in the properties definition (for instance, below the line that says LowPressureTransition = 6.0f;)
<syntaxhighlight lang="c">
 
#include <element.h>
 
 
int update_HETR(UPDATE_FUNC_ARGS) {
 
 
return 0;
 
}
 
</syntaxhighlight>
 
  
Before we go on with the actual code, we need to finish up a few things first so that the code actually knows there is a new update_HETR function.  Go back to powder.h at line ~250. You will see lots of <tt>int update_(UPDATE_FUNC_ARGS);</tt> This list is sorted alphabetically so lets put in our new HETR function.
 
 
<syntaxhighlight lang="c">
 
<syntaxhighlight lang="c">
int update_GOO(UPDATE_FUNC_ARGS);
+
DefaultProperties.tmp = 1; // This defines default properties
int update_HETR(UPDATE_FUNC_ARGS);
 
int update_HSWC(UPDATE_FUNC_ARGS);
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Remember that function variable in the ptypes array? we need to let it know that HETR has a special function to use, instead of NULL.  Replace NULL with &update_HETR.
 
<syntaxhighlight lang="c">
 
... "Heats objects it touches", ST_SOLID, TYPE_SOLID, &update_HETR, NULL},
 
</syntaxhighlight>
 
  
Now that our new HETR function will be called properly, we can go back into hetr.c and finish it up. NOTE: Put all code BEFORE the return 0; line so when it finishes running, it will go back to the main code.  If you kill the particle from inside the function, please return 1;.  Our HETR element will not die, so you don't have to worry about that.
 
  
Now we need to go over some useful ways of detecting particles, so that we can heat them.
+
Note that this doesn't allow random properties, for example, PHOT starts with a random vx and vy. To set dynamic properties per particle, you need to add a create function. Let's suppose we want to randomize the HETR's life between 0 and 100 for no reason. In the properties add this line.
<syntaxhighlight lang="c">
 
for(rx=-1; rx<2; rx++)
 
    for(ry=-1; ry<2; ry++)
 
</syntaxhighlight>
 
  
This code simply loops, generating coordinates in rx and ry to find neighbours, in this case, it is a 3x3 grid around the center one.  If you are having trouble getting this, try thinking about rx and ry, as a radius around the current particle.
 
 
<syntaxhighlight lang="c">
 
<syntaxhighlight lang="c">
for(rx=-2; rx<3; rx++)
+
Create = &Element_HETR::create;
    for(ry=-1; ry<2; ry++)
 
 
</syntaxhighlight>
 
</syntaxhighlight>
This would make the grid affected 5x3
 
<syntaxhighlight lang="c">
 
for(rx=-1; rx<2; rx++)
 
    for(ry=-2; ry<3; ry++)
 
</syntaxhighlight>
 
And this would flip the dimensions.
 
  
Add this:
+
Outside of the properties definition add the following lines:
<syntaxhighlight lang="c">
 
if(x+rx>=0 && y+ry>0 &&    x+rx<XRES && y+ry<YRES &&
 
                pmap[y+ry][x+rx] &&
 
                (pmap[y+ry][x+rx]&0xFF)!=PT_HETR&&
 
                (pmap[y+ry][x+rx]&0xFF)!=0xFF)
 
        {
 
</syntaxhighlight>
 
  
Your entire code should look like this so far:
 
 
<syntaxhighlight lang="c">
 
<syntaxhighlight lang="c">
        for(rx=-1; rx<2; rx++)
+
//#TPT-Directive ElementHeader Element_HETR static void create(ELEMENT_CREATE_FUNC_ARGS)
            for(ry=-1; ry<2; ry++)
+
void Element_HETR::create(ELEMENT_CREATE_FUNC_ARGS) {
1              if(x+rx>=0 && y+ry>0 && x+rx<XRES && y+ry<YRES &&
+
// Randomize life
2              pmap[y+ry][x+rx] &&
+
sim->parts[i].life = RNG::Ref().between(0, 100);
3              (pmap[y+ry][x+rx]&0xFF)!=PT_HETR&&
+
}
4              (pmap[y+ry][x+rx]&0xFF)!=0xFF)
 
5      {
 
 
</syntaxhighlight>
 
</syntaxhighlight>
1st line: If the current grid particle around the HETR pixel is within the screen, AND
 
  
2nd line: there is a particle in that point, AND
+
We use TPT's builtin random number generator to create a random number.
  
3rd line: that particle is not a HETR, AND (note: != means not equal)
 
  
4th line: that particle is not a wall,
 
  
5th line: THEN, do some code
+
'''BELOW IS FOR OLDER VERSIONS OF TPT ONLY!'''
  
 +
This is done inside of Simulation.cpp. Navigate to src/simulation/Simulation.cpp and find the function create_part. If you scroll down in this function, you will eventually find case statements that look like this:
  
Now add this:
 
 
<syntaxhighlight lang="c">
 
<syntaxhighlight lang="c">
r = pmap[y+ry][x+rx];
+
case PT_SOAP:
 +
parts[i].tmp = -1;
 +
parts[i].tmp2 = -1;
 +
break;
 +
case PT_ACID: case PT_CAUS:
 +
parts[i].life = 75;
 +
break;
 
</syntaxhighlight>
 
</syntaxhighlight>
  
It means you can just type 'r' instead of 'pmap[y+ry][x+rx]'. This will simplify code later on.
+
Adding default values is as simple as making a new case statement. HETR doesn't require any default values, but lets pretend we wanted .tmp to start out as "1". We would add a new statement (anywhere in the list, but near the end might be better) that looks like this:
NEW: because our hetr.c file is separate, we need to initialize these variables we are using inside hetr.c, add this as the first part of the update_HETR function.
+
 
 
<syntaxhighlight lang="c">
 
<syntaxhighlight lang="c">
int r, rx, ry;
+
case PT_HETR:
 +
parts[i].tmp = 1;
 +
break;
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Now add
+
Don't forget the "break;", without it wouldn't error, but your element might get some properties you didn't want it to have.
 +
 
 +
=== Step Five: Defining the Element's Special Properties ===
 +
 
 +
This is the part where we actually code what the element does. The HETR.cpp linked above already has an element function, which looks like this:
 +
 
 
<syntaxhighlight lang="c">
 
<syntaxhighlight lang="c">
if(parts[r>>8].temp + (parts[r>>8].temp*0.2f)<=MAX_TEMP)
+
//#TPT-Directive ElementHeader Element_HETR static int update(UPDATE_FUNC_ARGS)
 +
int Element_HETR::update(UPDATE_FUNC_ARGS)
 
{
 
{
 +
int r, rx, ry;
 +
for (rx = -1; rx < 2; rx++)
 +
for (ry = -1; ry < 2; ry++)
 +
if (BOUNDS_CHECK)
 +
{
 +
r = pmap[y+ry][x+rx];
 +
if (!r || TYP(r) == PT_HETR)
 +
r = sim->photons[y+ry][x+rx];
 +
if (!r)
 +
continue;
 +
if (parts[ID(r)].temp + (parts[ID(r)].temp*0.2f) <= MAX_TEMP)
 +
{
 +
parts[ID(r)].temp += parts[ID(r)].temp*0.2f;
 +
}
 +
else
 +
{
 +
parts[ID(r)].temp = MAX_TEMP;
 +
}
 +
}
 +
    return 0;
 +
}
 
</syntaxhighlight>
 
</syntaxhighlight>
Let's analyze.
 
  
1) <tt>if (a) { b }</tt>
+
This is a model for what most elements should look like. We can break it down line by line.
  
IF a is true, THEN b happens
 
  
2) <tt>parts[r>>8]</tt>  
+
<syntaxhighlight lang="c">
 +
//#TPT-Directive ElementHeader Element_HETR static int update(UPDATE_FUNC_ARGS)
 +
int Element_HETR::update(UPDATE_FUNC_ARGS)
 +
{
 +
</syntaxhighlight>
  
The currently selected particle (the one that's not HETR or a wall)
+
The first is the line that is read by generator.py and makes it work. Make sure this line is 100% correct or else your element won't compile. If it is not named HETR, you should change Element_HETR to match your element name.
  
3) <tt>.temp</tt>
 
  
means it's temperature.
+
<syntaxhighlight lang="c">
 +
int r, rx, ry;
 +
for (rx = -1; rx < 2; rx++)
 +
for (ry = -1; ry < 2; ry++)
 +
if (BOUNDS_CHECK)
 +
{
 +
</syntaxhighlight>
  
In English, the statement reads:
+
These lines start a search around the particle of HETR for things to heat up. It searches the 8 spaces directly surrounding HETR. It also searches the location the HETR itself is in, which is almost always unnecessary. You can fix this by changing the BOUNDS_CHECK line to <tt>if (BOUNDS_CHECK && (rx || ry))</tt>.
  
IF the particle's temperature + 20% of it's temperature is less then then the maximum temperature possible, THEN...
 
  
 
This ensures that when increasing the temperature, it won't go over the maximum temperature. Now add this:
 
 
<syntaxhighlight lang="c">
 
<syntaxhighlight lang="c">
parts[r>>8].temp += parts[r>>8].temp*0.2f;
+
r = pmap[y+ry][x+rx];
 +
if (!r || TYP(r) == PT_HETR)
 +
r = sim->photons[y+ry][x+rx];
 +
if (!r)
 +
continue;
 
</syntaxhighlight>
 
</syntaxhighlight>
  
In English,
+
These lines get the particle at location (x+rx, y+ry). It first checks if it exists, and then checks whether it isn't another particle of HETR (we don't want HETR heating up other HETR). If there is no particle in that location, it then checks whether any energy particles are in that location. If there isn't an energy particle either, it stops, continue; in C++ skips the entire for loop above and goes onto the next location.
  
Add 20% of the particle's temperature to itself.
+
For more information on pmap, photons, r, and i; go to [[Variables]]
  
  
Now add:
 
 
<syntaxhighlight lang="c">
 
<syntaxhighlight lang="c">
} else {
+
if (parts[ID(r)].temp + (parts[ID(r)].temp*0.2f) <= MAX_TEMP)
    parts[r>>8].temp = MAX_TEMP;
+
{
}
+
parts[ID(r)].temp += parts[ID(r)].temp*0.2f;
 +
}
 +
else  
 +
{
 +
parts[ID(r)].temp = MAX_TEMP;
 +
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
IF the particle's temperature + 20% of it's temperature is less then then the maximum temperature possible, THEN add 20% of the particle's temperature to itself, ELSE Set temperature to the maximum temperature.
+
This is the code unique to HETR, the rest was just a base used by almost every element. The temperature of the particle we found is stored in parts[ID(r)].temp. We want to multiply this by 1.2. If it's too close to MAX_TEMP, we just want to increase it to MAX_TEMP instead of doing the multiplication though. This code achieves just that.
 
 
  
Now close the two brackets we used for the if statements to complete the section.
 
The entire hetr.c should now look like this:
 
 
 
<syntaxhighlight lang="c">
 
<syntaxhighlight lang="c">
#include <element.h>
+
}
 
int update_HETR(UPDATE_FUNC_ARGS) {
 
    int r, rx, ry;
 
    for(rx=-1; rx<2; rx++)
 
        for(ry=-1; ry<2; ry++)
 
            if(x+rx>=0 && y+ry>0 && x+rx<XRES && y+ry<YRES &&
 
                pmap[y+ry][x+rx] &&
 
                (pmap[y+ry][x+rx]&0xFF)!=PT_HETR&&
 
                (pmap[y+ry][x+rx]&0xFF)!=0xFF)
 
    {
 
        r = pmap[y+ry][x+rx];
 
        if(parts[r>>8].temp+ (parts[r>>8].temp*0.2f)<=MAX_TEMP)
 
        {
 
            parts[r>>8].temp += parts[r>>8].temp*0.2f;
 
        }
 
        else
 
        {
 
            parts[r>>8].temp = MAX_TEMP;
 
        }
 
    }
 
 
     return 0;
 
     return 0;
}
+
}
 
</syntaxhighlight>
 
</syntaxhighlight>
Congrats, your HETR element should now work :).
 
  
What this code means in English:
+
Not much interesting here, except for the return 0; The function returns an int, so you should always have a return 0; at the end. If your particle gets killed during the update function, you should immediately return 1;. This will let the game know it died, and skip the movement code for it since it's already dead and doesn't need to move.
FOR all neighbours in a 3 pixel diameger, IF the particle's temperature + 20% of it's temperature is less then then the maximum temperature possible, THEN add 20% of the particle's temperature to itself, ELSE Set temperature to the maximum temperature.
+
 
 +
 
 +
Fore more complicated element functions, check out the list of useful [[Functions]].
  
 
 
== Part Two: Uploading Your Work to GitHub ==
 
== Part Two: Uploading Your Work to GitHub ==
 
'''(NOTE: GitHub is NOT necessary to just add elements, it is for getting code into the official)'''
 
'''(NOTE: GitHub is NOT necessary to just add elements, it is for getting code into the official)'''
Line 347: Line 226:
 
1) Open SmartGit (make sure you've saved your changes in Visual Studio).
 
1) Open SmartGit (make sure you've saved your changes in Visual Studio).
  
2) powder.c and any other files you may have changed should be listed as "Modified".
+
2) Simulation.cpp and any other files you may have changed should be listed as "Modified".
  
 
3) Press "Commit" at the top, list the things you have changed in the text box, and press "Commit".
 
3) Press "Commit" at the top, list the things you have changed in the text box, and press "Commit".
  
 
4) Press "Push" at the top, and press "Push" again.
 
4) Press "Push" at the top, and press "Push" again.
 
5) Go to your Powder Toy repository page on GitHub and press "Pull Request" at the top.
 
 
6) Do not send the request to Simon if it is the element created in this tutorial. He will not accept it. If it's a very good and very useful element, send the request to facialturd (Simon's username) and you should be done. Verify that the code has been changed if you like.
 
 
7) If Simon decides to accept your request, your code will be in the official Powder Toy source code. Congratulations!
 
 
  
  

Latest revision as of 11:33, 14 March 2022

Language: English  • русский

ATTENTION: This guide is severely out of date as of 2021. Disregard everything you see below this notice. This should be fixed soon. Until then, the quick and informal one-sentence tutorial is as follows: successfully compile TPT first following this guide, then create a new element file in src/simulation/elements based on other element files in the same directory, add it to the list in src/simulation/elements/meson.build, then recompile.

This tutorial will give you guidelines on creating an element in The Powder Toy. We will use the heater (HETR) element in this example, which you can find here. The color will be the same as the HEAT element, and it will be an indestructible solid in the special menu, that transfers heat quickly. If you have any problems please post a thread on the forums

It's not as simple as typing the name, color, and features, but it's almost that easy.

Part One: Defining the Element's Properties

Step One: Defining the Element

Create a new element file, (HETR.cpp for this example, or whatever name your element will be) inside of src/simulation/elements.

After you put this into the /elements folder, you have to add it to the solution.

1. Open up your solution file, then go to the Solution Explorer pane.

2. Go to src/simulation/elements/

4. Right click the 'elements' folder

5. Go to Add -> Existing file

6. Navigate to src/simulation/elements and double click your element file HETR.cpp

Your new element should now be included in the solution! If you don't do this, you will get errors when you try compiling your new mod.

Open ElementClasses.h in the editor of your choice (Visual Studio for windows users). ElementClasses.h is located under Source Files -> generated in the Solution Explorer. Double click it to open it up. You will see a file that should have a big list of #define PT_XXXX Y. Scroll down until you reach the end of this list of statements that follow this format. Remember this number. You will need to enter a number greater than this one into the .cpp file you create for your new element. Currently, the largest element ID is LDTC, 186. Your element should have an ID of 187.

You should not edit ElementClasses.h yourself, this file is generated automatically when generator.py is ran. It uses the "//#TPT-Directive" comments to do this, so make sure you have the element fully written before you run it. For Visual Studio you have to run generator.py manually every time you finish making a new element. The Visual Studio compiling guide should have given a good explanation. If you didn't read that, then here is a short version:

1. Locate the folder where your source code is located.

2. In this directory there should be a file named "generator.py"

3. Double click it to run it. A black window should appear for a second or so, then disappear. This means that it worked. You can check to see if ElementClasses.h was updated to confirm.

Step Two: Defining the Element's Primary Properties

Now, open up your new element file. It is empty right now, it is recommended you copy from another element, or this template here: HETR.cpp . The file is entirely commented, you can just change the properties to how you want.

Please look at the full list of Properties is here: Element_Properties

This is a lot to handle, and if you feel overwhelmed by some of the choices, try looking at elements similar to what you are creating and copy the values from those.

Step Three: Defining the Element's State Changes

In the linked property list page you will notice some special ones named LowPressure, LowPressureTransition, etc. These control all state changes for high/low pressure and temperature. It is very easy to edit these and add in transitions. Lets take GAS as an example. In GAS.cpp, you will find this:

	LowPressure = IPL;
	LowPressureTransition = NT;
	HighPressure = 6.0f;
	HighPressureTransition = PT_OIL;
	LowTemperature = ITL;
	LowTemperatureTransition = NT;
	HighTemperature = 573.0f;
	HighTemperatureTransition = PT_FIRE;

This makes it change into OIL at higher than 6.0 pressure, and change into FIRE at higher than 573.0K. Note that all temperatures are in Kelvin, so you have to subtract 273.15 to get the temperature in Celcius. In this case it transitions at 299.85C.

For some transitions, there is one more step. If you want it to transition back, you need to add similar code into the other element. Lets say you wanted OIL to change back into GAS once it goes under 6.0 pressure again. You would need to go into OIL.cpp and change the pressure transitions to this:

	LowPressure = PT_GAS;
	LowPressureTransition = 6.0f;

NOTE: For an element that does NOT have a transition at high/low pressure/temp, please follow the same format as the others and use IPL,IPH,ITL,ITH and NT.

HETR is very simple and has no transitions, so everything should be IPL,IPH,ITL,ITH and NT.

Step Four: Defining initial values

Some elements start off with certain properties by default, for example PHOT gets a .life value of 680.

CURRENT VERSION OF TPT`

In the current version of TPT, you can directly modify a DefaultProperties variable. For example, if we wanted .tmp to start out as "1" for HETR, we can write anywhere in the properties definition (for instance, below the line that says LowPressureTransition = 6.0f;)

DefaultProperties.tmp = 1; // This defines default properties


Note that this doesn't allow random properties, for example, PHOT starts with a random vx and vy. To set dynamic properties per particle, you need to add a create function. Let's suppose we want to randomize the HETR's life between 0 and 100 for no reason. In the properties add this line.

Create = &Element_HETR::create;

Outside of the properties definition add the following lines:

//#TPT-Directive ElementHeader Element_HETR static void create(ELEMENT_CREATE_FUNC_ARGS)
void Element_HETR::create(ELEMENT_CREATE_FUNC_ARGS) {
	// Randomize life
	sim->parts[i].life = RNG::Ref().between(0, 100);
}

We use TPT's builtin random number generator to create a random number.


BELOW IS FOR OLDER VERSIONS OF TPT ONLY!

This is done inside of Simulation.cpp. Navigate to src/simulation/Simulation.cpp and find the function create_part. If you scroll down in this function, you will eventually find case statements that look like this:

			case PT_SOAP:
				parts[i].tmp = -1;
				parts[i].tmp2 = -1;
				break;
			case PT_ACID: case PT_CAUS:
				parts[i].life = 75;
				break;

Adding default values is as simple as making a new case statement. HETR doesn't require any default values, but lets pretend we wanted .tmp to start out as "1". We would add a new statement (anywhere in the list, but near the end might be better) that looks like this:

			case PT_HETR:
				parts[i].tmp = 1;
				break;

Don't forget the "break;", without it wouldn't error, but your element might get some properties you didn't want it to have.

Step Five: Defining the Element's Special Properties

This is the part where we actually code what the element does. The HETR.cpp linked above already has an element function, which looks like this:

//#TPT-Directive ElementHeader Element_HETR static int update(UPDATE_FUNC_ARGS)
int Element_HETR::update(UPDATE_FUNC_ARGS)
{
	int r, rx, ry;
	for (rx = -1; rx < 2; rx++)
		for (ry = -1; ry < 2; ry++)
			if (BOUNDS_CHECK)
			{
				r = pmap[y+ry][x+rx];
				if (!r || TYP(r) == PT_HETR)
					r = sim->photons[y+ry][x+rx];
				if (!r)
					continue;
				if (parts[ID(r)].temp + (parts[ID(r)].temp*0.2f) <= MAX_TEMP)
				{
					parts[ID(r)].temp += parts[ID(r)].temp*0.2f;
				}
				else 
				{
					parts[ID(r)].temp = MAX_TEMP;
				}
			}
    return 0;
}

This is a model for what most elements should look like. We can break it down line by line.


//#TPT-Directive ElementHeader Element_HETR static int update(UPDATE_FUNC_ARGS)
int Element_HETR::update(UPDATE_FUNC_ARGS)
{

The first is the line that is read by generator.py and makes it work. Make sure this line is 100% correct or else your element won't compile. If it is not named HETR, you should change Element_HETR to match your element name.


	int r, rx, ry;
	for (rx = -1; rx < 2; rx++)
		for (ry = -1; ry < 2; ry++)
			if (BOUNDS_CHECK)
			{

These lines start a search around the particle of HETR for things to heat up. It searches the 8 spaces directly surrounding HETR. It also searches the location the HETR itself is in, which is almost always unnecessary. You can fix this by changing the BOUNDS_CHECK line to if (BOUNDS_CHECK && (rx || ry)).


				r = pmap[y+ry][x+rx];
				if (!r || TYP(r) == PT_HETR)
					r = sim->photons[y+ry][x+rx];
				if (!r)
					continue;

These lines get the particle at location (x+rx, y+ry). It first checks if it exists, and then checks whether it isn't another particle of HETR (we don't want HETR heating up other HETR). If there is no particle in that location, it then checks whether any energy particles are in that location. If there isn't an energy particle either, it stops, continue; in C++ skips the entire for loop above and goes onto the next location.

For more information on pmap, photons, r, and i; go to Variables


				if (parts[ID(r)].temp + (parts[ID(r)].temp*0.2f) <= MAX_TEMP)
				{
					parts[ID(r)].temp += parts[ID(r)].temp*0.2f;
				}
				else 
				{
					parts[ID(r)].temp = MAX_TEMP;
				}

This is the code unique to HETR, the rest was just a base used by almost every element. The temperature of the particle we found is stored in parts[ID(r)].temp. We want to multiply this by 1.2. If it's too close to MAX_TEMP, we just want to increase it to MAX_TEMP instead of doing the multiplication though. This code achieves just that.

			}
    return 0;
}

Not much interesting here, except for the return 0; The function returns an int, so you should always have a return 0; at the end. If your particle gets killed during the update function, you should immediately return 1;. This will let the game know it died, and skip the movement code for it since it's already dead and doesn't need to move.


Fore more complicated element functions, check out the list of useful Functions.

Part Two: Uploading Your Work to GitHub

(NOTE: GitHub is NOT necessary to just add elements, it is for getting code into the official)

1) Open SmartGit (make sure you've saved your changes in Visual Studio).

2) Simulation.cpp and any other files you may have changed should be listed as "Modified".

3) Press "Commit" at the top, list the things you have changed in the text box, and press "Commit".

4) Press "Push" at the top, and press "Push" again.


Now you are done, if you have any more questions, type them at the discussion part of this page.

Welcome to coding the powder toy!