Difference between revisions of "Coding-tutorial"

From The Powder Toy
Jump to: navigation, search
(Corrected property names)
m (Reverted edits by JohnLolFun (talk) to last revision by LBPHacker)
 
(48 intermediate revisions by 20 users not shown)
Line 1: Line 1:
For a video tutorial, check out:
+
{{Languages|Coding-tutorial}}
''<ins>[http://www.youtube.com/watch?v=SYl5eEQ6Mus| gamerboy8864's Tutorial on how to mod The Powder Toy]</ins>
 
 
 
 
 
 
 
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, if you have any problems please contact me, if there are any obvious errors, feel free to correct.
 
  
 +
'''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.  
  
 +
== Part One: Defining the Element's Properties ==
  
 +
=== Step One: Defining the Element ===
  
Note: Line numbers given here will probably change as more code is added. Look in the general area of the line number given. Use your editors "Find" tool to get the precise line number.
+
Create a new element file, (HETR.cpp for this example, or whatever name your element will be) inside of src/simulation/elements.
 
 
 
 
 
 
'''Part One: Defining the Element's Properties'''
 
 
 
 
 
 
 
'''Step One: Defining the Element'''
 
 
 
Open powder.h in the editor of your choice (Visual Studio for windows users) and go to ~line 217 (Find: #define PT_NUM)
 
#define PT_NONE 0
 
#define PT_DUST 1
 
 
...
 
 
#define PT_GBMG 157
 
#define PT_FIGH 158
 
#define PT_NUM  159
 
 
 
Notice each element has an incrementing ID and the last number in the list is equal to the number of elements (it is one higher then the highest because the elements start on 0)? This is necessary to note because it is necessary to change when adding new elements.
 
 
 
lets add a new value.
 
 
 
Each element's number is incremented by one. PT_NUM is the number of elements in the game (PT_NONE starts at zero).
 
 
 
#define PT_FIGH 158
 
#define PT_HETR 159
 
#define PT_NUM  160
 
 
 
When adding an element, place it before PT_NUM. Give it the number PT_NUM had previously and add one to PT_NUM's number. The elements should still increment by one.
 
 
 
 
 
 
 
'''Step Two: Defining the Element's Primary Properties'''
 
 
 
Still in powder.h (in the future, this may be moved into elementdata.c, line 172), go to ~line 654 (Find: {"FIGH", PIXPACK(0x000000)...
 
 
 
{"", PIXPACK(0x000000), 0.0f, 0.00f * CFDS, 1.00f, 0.00f, 0.0f, 0.0f, 0.00f, 0.000f * CFDS, 0, 0, 0, 0, 1, 1, 1, ...
 
{"DUST", PIXPACK(0xFFE0A0), 0.7f, 0.02f * CFDS, 0.96f, 0.80f, 0.0f, 0.1f, 0.00f, 0.000f * CFDS, 1, 10, 0, 0, ...
 
.....
 
{"FIGH", PIXPACK(0x000000), 0.5f, 0.00f * CFDS, 0.2f, 1.0f, 0.0f, 0.0f, 0.0f, 0.00f * CFDS, 0, 0, 0, 0, 0, 1, 1...
 
//Name Colour Advec...
 
 
 
 
 
These are the primary definitions for the elements. You can see what each variable means at the top of the code as well as just below.
 
 
 
'''Name''': The name of the element. Try to use 4 letters, but some elements only have 3 (or 5)
 
 
 
 
 
'''Color''': Color in hexadecimal code. Go to http://www.colorpicker.com/ to find the hexadecimal code (at the top) for your color. The hexadecimal code goes AFTER the "0x" prefix, always.
 
 
 
 
 
'''Advection''': How much the particle is accelerated by moving air.
 
 
 
 
 
'''Airdrag''': How much air the particle generates in the direction of travel.
 
 
 
 
 
'''Airloss''': How much the particle slows down moving air (although this won't have as big an effect as a wall). 1 = no effect, 0 = maximum effect.
 
 
 
 
 
'''Loss''': How much velocity the particle loses each frame. 1 = no loss, .5 = half loss.
 
 
 
 
 
'''Collision''': Velocity is multiplied by this when the particle collides with something.
 
 
 
 
 
'''Gravity'': How fast the particle falls. A negative number means it floats.
 
 
 
 
 
'''Diffusion''': How much the particle "wiggles" around (think GAS).
 
 
 
 
 
'''Hotair''': How much the particle increases the pressure by.
 
 
 
 
 
'''Falldown''': How does the particle move? 0 = solid, 1 = powder, 2 = liquid
 
 
 
 
 
'''Flammable''': Does it burn? 0 = no, higher numbers = higher "burnage".
 
 
 
 
 
'''Explosive''': Does it explode? 0 = no, 1 = when touching fire, 2 = when touching fire or when pressure > 2.5
 
 
 
 
 
'''Meltable''': Does it melt? 1 = yes, 0 = no.
 
 
 
 
 
'''Hardness''': How much does acid affect it? 0 = no effect, higher numbers = higher effect.
 
 
 
 
 
'''Enabled''': Can it be created with the brush (or console)? 1 = yes, 0 = no. Always use 1
 
 
 
 
 
'''Menu''': Does it show up on the menu? 1 = yes, 0 = no. Always use 1
 
 
 
 
 
'''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.
 
 
 
 
 
'''Section''': The section of the menu it is in. Prefix everything with 'SC_'. Look at interface.h line 36 for the different section names
 
 
 
 
 
'''Heat''': What temperature does it have when created? Temperature is in Kelvin (Kelvin = degrees C + 273.15). R_TEMP+273.15f gives room temperature.
 
 
 
 
 
'''Hconduct''': specific heat value (how fast it transfers heat to particles touching it), can be found by using the real life heat value in J/G K (or KJ/KG K) by 96.635/RealLifeValue. 0 - no heat transfer, 250 - 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.
 
  
 +
After you put this into the /elements folder, you have to add it to the solution. 
  
'''Properties''': Does this element have special properties? The properties can be found at ~232Separate each property with | inside the property variable. Some properties are below
+
1Open up your solution file, then go to the Solution Explorer pane.
  
 +
2.  Go to src/simulation/elements/
  
'''Function''':  This is new, and adds a huge performance increase, for now please put NULL here, we will come back to this later.
+
4.  Right click the 'elements' folder
  
 +
5.  Go to Add -> Existing file
  
'''Graphics Function''':  This is more new, and was created with the new drawing system. Put NULL here, unless you know how to create a graphics function
+
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.
  
Properties:
+
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.
There are 5 properties for the different states:
+
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.
  
TYPE_PART(powders), TYPE_LIQUID, TYPE_SOLID, TYPE_GAS, and TYPE_ENERGY. You should pick one of these to use for your element.
+
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:
  
If your element conducts electricity, use PROP_CONDUCTS.
+
1.  Locate the folder where your source code is located.
  
PROP_DEADLY makes your element kill stickmen.
+
2. In this directory there should be a file named "generator.py"
  
PROP_HOT_GLOW makes your element glow when hot, like metl does.
+
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.
  
PROP_RADIOACTIVE makes your element radioactive.
+
=== Step Two: Defining the Element's Primary Properties ===
  
There are a few more properties, but they are slightly less useful or don't do anything yet.
+
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.
  
 +
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.
  
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.
+
=== Step Three: Defining the Element's State Changes ===
...
 
{"FIGH", PIXPACK(0x000000),    0.5f, 0.00f * CFDS,    0.2f,      1.0f, 0.0f,    0.0f,    0.0f, ...
 
{"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},
 
};
 
  
'''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:
 +
<syntaxhighlight lang="c">
 +
LowPressure = IPL;
 +
LowPressureTransition = NT;
 +
HighPressure = 6.0f;
 +
HighPressureTransition = PT_OIL;
 +
LowTemperature = ITL;
 +
LowTemperatureTransition = NT;
 +
HighTemperature = 573.0f;
 +
HighTemperatureTransition = PT_FIRE;
 +
</syntaxhighlight>
  
 +
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:
Still 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
+
LowPressure = PT_GAS;
// Name     plv plt phv pht tlv tlt   thv tht
+
LowPressureTransition = 6.0f;
/* NONE */ {IPL, NT, IPH, NT, ITL, NT, ITH, NT},
+
</syntaxhighlight>
/* DUST */ {IPL, NT, IPH, NT, ITL, NT, ITH, NT},
 
 
 
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:
 
/* WATR */ {IPL, NT, IPH, NT, 273.15f,PT_ICEI, 373.0f, PT_WTRV},
 
 
 
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:
 
/* ICE  */ {IPL, NT, 0.8f, PT_SNOW, ITL, NT, 233.0f, ST},
 
 
 
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.
...
 
    /* FIGH  */ {IPL, NT, IPH, NT, ITL, NT, ITH, NT},
 
    /* HETR  */ {IPL, NT, IPH, NT, ITL, NT, ITH, NT},
 
};
 
  
 +
=== Step Four: Defining initial values ===
  
'''Step Four: Defining the Element's Special Properties'''
+
Some elements start off with certain properties by default, for example PHOT gets a .life value of 680.
  
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.
+
'''CURRENT VERSION OF TPT`
  
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.
+
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;)
  
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.
+
<syntaxhighlight lang="c">
#include <element.h>
+
DefaultProperties.tmp = 1; // This defines default properties
+
</syntaxhighlight>
int update_HETR(UPDATE_FUNC_ARGS) {
 
 
return 0;
 
}
 
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 int update_''''''(UPDATE_FUNC_ARGS); This list is sorted alphabetically so lets put in our new HETR function.
 
int update_GOO(UPDATE_FUNC_ARGS);
 
int update_HETR(UPDATE_FUNC_ARGS);
 
int update_HSWC(UPDATE_FUNC_ARGS);
 
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.
 
... "Heats objects it touches", ST_SOLID, TYPE_SOLID, &update_HETR},
 
  
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.
 
for(rx=-1; rx<2; rx++)
 
    for(ry=-1; ry<2; ry++)
 
  
This code simply means "any particle touching a heater particle".
+
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.
  
It basically sets the grid size in which particles are affected by the effect of the particle. 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">
for(rx=-2; rx<3; rx++)
+
Create = &Element_HETR::create;
    for(ry=-1; ry<2; ry++)
+
</syntaxhighlight>
This would make the grid affected 5x3
 
for(rx=-1; rx<2; rx++)
 
    for(ry=-2; ry<3; ry++)
 
And this would flip the dimensions.
 
  
 +
Outside of the properties definition add the following lines:
  
 +
<syntaxhighlight lang="c">
 +
//#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);
 +
}
 +
</syntaxhighlight>
  
Add this:
+
We use TPT's builtin random number generator to create a random number.
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)
 
        {
 
  
  
  
Your entire code should look like this so far:
+
'''BELOW IS FOR OLDER VERSIONS OF TPT ONLY!'''
        for(rx=-1; rx<2; rx++)
 
            for(ry=-1; ry<2; ry++)
 
1              if(x+rx>=0 && y+ry>0 && x+rx<XRES && y+ry<YRES &&
 
2              pmap[y+ry][x+rx] &&
 
3              (pmap[y+ry][x+rx]&0xFF)!=PT_HETR&&
 
4              (pmap[y+ry][x+rx]&0xFF)!=0xFF)
 
5      {
 
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
+
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:
  
3rd line: that particle is not a HETR, AND (note: != means not equal)
+
<syntaxhighlight lang="c">
 +
case PT_SOAP:
 +
parts[i].tmp = -1;
 +
parts[i].tmp2 = -1;
 +
break;
 +
case PT_ACID: case PT_CAUS:
 +
parts[i].life = 75;
 +
break;
 +
</syntaxhighlight>
  
4th line: that particle is not a wall,
+
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:
  
5th line: THEN, do some code
+
<syntaxhighlight lang="c">
 +
case PT_HETR:
 +
parts[i].tmp = 1;
 +
break;
 +
</syntaxhighlight>
  
 +
Don't forget the "break;", without it wouldn't error, but your element might get some properties you didn't want it to have.
  
Now add this:
+
=== Step Five: Defining the Element's Special Properties ===
r = pmap[y+ry][x+rx];
 
  
It means you can just type 'r' instead of 'pmap[y+ry][x+rx]'. This will simplify code later on.
+
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:
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.
 
int r, rx, ry;
 
  
Now add
+
<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)
Let's analyze.
+
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>
  
1) if ()
+
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) parts[r>>8]
+
<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) .temp
 
  
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>
  
 +
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>.
  
In English, the statement reads:
 
  
IF the particle's temperature + 20% of it's temperature is less then then the maximum temperature possible, THEN...
+
<syntaxhighlight lang="c">
 +
r = pmap[y+ry][x+rx];
 +
if (!r || TYP(r) == PT_HETR)
 +
r = sim->photons[y+ry][x+rx];
 +
if (!r)
 +
continue;
 +
</syntaxhighlight>
  
 +
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.
  
This ensures it won't go over the maximum temperature. Now add this:
+
For more information on pmap, photons, r, and i; go to [[Variables]]
parts[r>>8].temp += parts[r>>8].temp*0.2f;
 
  
In English,
 
  
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.
+
<syntaxhighlight lang="c">
 +
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;
 +
}
 +
</syntaxhighlight>
  
 +
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 add:
+
<syntaxhighlight lang="c">
else {
+
}
    parts[r>>8].temp = MAX_TEMP;
 
}
 
 
 
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 the temperature is the maximum temperature.
 
 
 
 
 
Now close the two brackets we used for the if statements to complete the section.
 
The entire hetr.c should now look like this:
 
#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;
}
+
}
Congrats, your HETR element should now work.
+
</syntaxhighlight>
 
 
 
 
 
 
 
 
 
 
 
  
 +
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)
+
== 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).
 
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!