ES3- mod and element editing instructions

[LE4dGOLEM]

Master Hector: I felt this should be stickied, since people are still making threads asking how to code for ES3 and there isn't any better guide around.


Enigmasand Guide Alpha3 ver. 1.02
Well, I made a guide for [url="http://fallingsandgame.com/viewtopic.php?t=514"]wxSand[/url], so I'm gonna give Enigmasand a go ^_^.

BASIC ELEMENTS

Because Enigmasand uses XML, all elements and reactions are in tags.
let us take, for example, Wall.

Code: Select all

<element name="WALL" color="ff808080">
</element>


The code tells us that the element is called "WALL" and it's colour is ff808080. "808080" is a darkish grey colour in Hex. The First "ff" is the Alpha Channel (currently not supported). Leave this in.
Wall also has a </element> tag straight after the opening tag, so we know it has no gravity and is inert.

ELEMENTS WITH GRAVITY

Elements that have gravity and reactions are more complex;

Code: Select all

<element name="SAND" color="FFEECC80" dens="1.4">
<gravity g="0.95" r="0.25"/>
</element>


So, It's called sand; it's fairly sand coloured; it has a relative density of 1.4 (water has relative density 1 (like in real life), so sand will sink in water); It falls at a rate of 0.95 and slips at a rate of 0.25. Remember to end the reaction tag with "/>" rather than just ">"

ELEMENTS WITH REACTIONS

Self Reactions

Code: Select all

<element name="FIRE" color="ffff4040" dens="0.01">
<gravity g="-0.15" r="0.05"/>
<self chance="0.1" result="BLANK"/>
</element>


It's called Fire, it's red, it has a very low density, it has a slow Negative Gravity.
More Importantly, it has a Self tag.

Code: Select all

<self chance="0.1" result="BLANK"/>

So, every ten Frames (as in, Frames per Second), the result is "BLANK": it Selfs into Empty. Remember to end the tag with "/>" and not just ">"

Neighbor Reactions

Code: Select all

<element name="PLANT" color="ff20cc20">
<reaction chance="0.3" trigger="FIRE" res1="1.0" ares1="FIRE" bres1="FIRE"/>
<reaction chance="0.1" trigger="WATER" res1="1.0" ares1="PLANT" bres1="PLANT"/>
</element>


Plant. It's green, It doesnt fall.

It has Neighbor Reactions.

Code: Select all

<reaction chance="0.1" trigger="WATER" res1="1.0" ares1="PLANT" bres1="PLANT"/>

It's a Reaction. 0.1 means every 10 Frames. The trigger for the Reaction is Water. "res1" is 1, similar to the "1" in wxSand code...

Code: Select all

neighbor   0.2 Plant Water [b]1[/b] Plant Plant

...That can be a 0.5 and have another 0.5 [Edit: Or 0.25 and 0.25 and 0.5. Or any number of decimals assuming the total is 1.0]
"ares1" is "Plant". This means the Plant stays as Plant.
"bres1" is "Plant". This Means the Water turns into Plant.

ELEMENTS NOT IN THE LIST

"Okay, I've looked played the game," you say, "but where's Molten Cera? That's not in the element list!"
let's look at the .xml file:

Code: Select all

<element name="CERA2" color="ffeeddcd" menu="0" dens="1.3">
<gravity g="1.0" r="0.35"/>
<self chance="0.4" result="CERA"/>
</element>


Aha! Cera2 has an extra peice of information in the tag; "menu=0". THis means that, whilst it won't appear in the menu, it still features in the game.

EXPLOSIONS
Explosions work thusly:

Code: Select all

<explosion chance="chance from 0 - 1" trigger="what causes the explosion" type="TYPE" sizex="size of explosion" result="what it explodes into"/>


type="0" are cirular explosions
type="1" are firework-like explosions.


PHYSICS

Because Enigmasand is in XML, you have to tell it what it is. Start any Enigmasand Physics file with

Code: Select all

<enigmasand>


and end it with

Code: Select all

</enigmasand>


LOADING MODS
Save the Mod as "default.xml" and open Enigmasand. Backup the normal deafult.xml file.


-LE4dGOLEM

WILL ADD MORE LATER!

[xavierenigma]

Thanks for documenting this. If you have any questions on things you can't figure out, just pm me.

The first ff in the color represents the alpha channel which is currently not even supported (e.g. FFEECC80==EECC80)

[LE4dGOLEM]

Thanks for documenting this. If you have any questions on things you can't figure out, just pm me.

The first ff in the color represents the alpha channel which is currently not even supported (e.g. FFEECC80==EECC80)

No Problem.

What happened to explosions by the way?

[Tech..]

Yeah the explosions (or movement on neighbor reaction)
are kinda missing. You should really build out this element creation,
just one future more than WxSand and this will become more popular
(move on reaction or pressure maybe).

Why did you put the colors in hexademical? RGB colors are easier
to 'predict' (for me that is).

Are there any other functions yet or not?


Finally I'd like to ask you to give us the opportunity to make
multiple EMPTIES, that boost creativity by alot.

[LE4dGOLEM]

Finally I'd like to ask you to give us the opportunity to make
multiple EMPTIES, that boost creativity by alot.

Lol.

Code: Select all

<element name="???" color="ffff00ff">
<reaction chance="0.95" trigger="BLANK" res1="1.0" ares="???" bres="???"/>
<self chance="0.001" result="Leftover???"/>
</element>

How come this Doesn't work?

[Tech..]

No question marks allowed maybe?

Try naming it Pie.

[LE4dGOLEM]

No Luck . xavierenigma! What's going on?!

[xavierenigma]

Code: Select all

<element name="???" color="ffff00ff">
<reaction chance="0.95" trigger="BLANK" res1="1.0" ares="???" bres="???"/>
<self chance="0.001" result="Leftover???"/>
</element>

How come this Doesn't work?

The problem here is with the reaction tag. It should be:

Code: Select all

<element name="???" color="ffff00ff">
<reaction chance="0.95" trigger="BLANK" res1="1.0" ares1="???" bres1="???"/>
<self chance="0.001" result="Leftover???"/>
</element>

The numbers following ares and bres are used to distinguish the a and b results from alternate possibilities.

[xavierenigma]

Of course, I haven't forgotten what makes EnigmaSand (That is, the unique explosions). In this release, I merely wanted to come close to wxSand.

I'm not completely unaware of what the community wants. I'm planning to include a few special features as well as some modifications to the reaction and self tags.


To clarify a few things, many attributes (Attributes being variables within tags: <tag attribute="value"/>) are optional. Here is a list of attributes for each tag. I've taken the liberty to include planned attributes or attributes which are currently unsupported;

<element name="SAND" color="FFEECC80" dens="1.4" cond="0"> </element>

element
-name
-color (Reserved color: ff000001 (blank/empty))
-dens (Density optional default=0.0 Note: 0.0 results in no physics support for density)
-cond (Conductivity optional default=0.0)

<gravity g="0.95" r="0.25"/>
gravity
-g (Rate at which the element falls in the imaginary gas called blank)
-r (rate of slip)

<reaction chance="0.1" trigger="FIRE" res1="0.7" ares1="FIRE" bres1="FIRE" res2="0.3" ares2="FIRE" bres2="CERA2"/>
reaction
-chance Chance of reaction occurring
-trigger Element required to begin reaction
-direction (optional default: ALL) Values: UP, DOWN, ADJ, ALL
-temp (optional)Tempurature requirement for reaction
-res<num> Chance of this result occurring
-ares<num> Result for current pixel/reactant pixel
-bres<num> Result for trigger pixel
-cres<num> (optional) Fills this and all adjacent pixels with result (overrides ares/bres)

<self chance="0.4" result="CERA"/>

self
-chance Chance of reaction occuring
-temp (optional)Tempurature requirement for reaction
-result Resulting element
-cresult (optional) Fills all adjacent pixels with result


Tags being considered:
zombie- Handle interactions between elements and zombies
attributes undecided

explosion- Handle reactions which cause explosions
type- 0-Flash/1-Particle. Flash being the C-4 style explosion and Particle being the Nitro[glycerin] style explosion from Enimga2
sizex- Multiplier for explosion size
result- residual element of the explosion (All EnigmaSand2 explosions resulted in fire alone)



Issues:
Multiple empties: you can create multiple empties/blanks by assigning a color very close to the default blank color: ff000001.

Hexadecimal RGB values: First of all, Hexadecimal numbers are RGB. There's nothing different other than the base. I chose hexadecimal simply because its simple to parse and takes up less space. (Each two digits in a hexadecimal value represent a number. The 8 digits make a color in the format ARGB where A is the alpha, R is the red, G is the green, and B is the blue) I may include a color chooser later on.

Zombies: I've been putting them off but eventually they will be added.

Heat and Pressure: Heat will definitely be included soon. Pressure may not be readily available. My algorithms weren't as well thought out as I thought they were so unless someone is willing to develop something, pressure may be out of the picture for a while.

I'm far from done and I'll try and update often.

[Dans_Gnillaf]

i think the user interface should be changed, because if someone is going to make a mod with 100 + elements, it might start getting messy.