From FSG Wiki

The wxSand "Physics File" defines the elements that can be used, element properties & interactions, and the sources that fall from the top of the screen.

wxSand no longer overrides default.txt, instead it will load it if present. If no default.txt is present, the default physics file will be created as default.txt and loaded.

Contents 1 File Format 2 Directives 2.1 Element 2.2 HotColor 2.3 Self 2.4 HotSelf 2.5 Neighbor 2.6 HotNeighbor 2.7 Sources 2.8 Group 2.9 Explosion 2.10 PExplosion 3 Examples 3.1 Element 3.2 Neighbor 3.3 HotSelf 3.4 HotNeighbor 4 Probabilities 5 Element Overview 5.1 Solids/Rigids 5.2 Liquids/Fluids/Particulates 5.3 Gases/Plasmas 6 References

File Format

The format of the physics file has changed over time. The old version, referred to as "subversion 1", is no longer in the scope of this document.

The physics file is a text file containing one directive or comment per line. Additional line breaks between directives are ignored. Directive parameters should be separated by either tabs or spaces. In order to correctly interpret a physics file, the text "subversion 2" must occur somewhere in the file.

All element names are case sensitive and all references to them must be identical between directives.

Directives

The wxSand physics file has 8 directives that define and control the function of the program. Each line must start with either a directive or be a comment.

• Element, Defines the basic properties of an element.
• HotColor, Defines the color of an element as it's temperature rises (gains energy).
• Self, Defines what an element will degenerate into.
• HotSelf, Defines the minimum temperature (energy) before the degeneration defined in "self" can take place.
• Neighbor, Defines interactions with neighboring (touching) elements.
• HotNeighbor, Defines the minimum temperature (energy) before a specific neighbor interaction can take place.
• Sources, Defines which elements are sources.
• Group, Arranges the elements into different groups. Any elements not in a group will default to the "Misc" group.
• Explosion, Causes reactions to explode outward.
• PExplosion, Causes elements to fill a radius.
• #, Denotes a comment. Comments preceeding an element directive are used as the long description of an element.

Element

The element directive defines the basic properties of an element.

Syntax:

element  NAME  R G B  GRAVITY  SLIP  DENSITY  CONDUCTIVITY  VISIBLE

• NAME - The name of the element.
• R,G,B - The color of the element in RGB (Red/Green/Blue) format. Must be an integer between 0 and 255.
• GRAVITY - The speed at which an element falls. The higher the number the faster the element falls. An element with a value of 0 will not move and a negative values mean the element will rise.
• SLIP - How quickly the element will spread out as it falls/rises. A value of 0 means the element will not spread out at all. Slip is dependant on gravity.
• DENSITY - How heavy the element is relative to other elements. Elements with lower densities will float above elements with higher densities.
• CONDUCTIVITY - How quickly the element absorbs and transmits heat (energy). A value of 0 means the element will not absorb or transmit any energy. Values above 1 means the element gives off energy. Example: Fire (energy 1.1) heats up water at a speed of 0.5, because water has an energy of 0.4.
• VISIBLE - Whether the element can be selected. A value of 1 shows the element, 0 hides it.

HotColor

Defines the color of an element as it's temperature rises (gains energy). As an element's temperature rises it's color will scale from it's normal temperature to the one defined by HotColor.

Syntax:

hotcolor  ELEMENT  R  G  B 

• ELEMENT - The name of the element this line refers to.
• R,G,B - The color of the element in RGB (Red/Green/Blue) format.

Self

Defines what an element will degenerate into.

Syntax:

self  RATE  ELEMENT  PROBABILITY  RESULT  [PROBABILITY  RESULT]..

• RATE - The probability (1.0 being 100%) of a reaction happening (per frame).
• ELEMENT - The name of the element this line refers to.
• PROBABILITY - The probability that the result of the reaction will be the following. Only supports 1 decimal place.
• RESULT - The element this reaction results in.

(The probability and result parameters may be repeated multiple times. The sum of all of the probabilities must be 1.)

HotSelf

Defines the minimum temperature (energy) before the degeneration defined in "self" can take place.

Syntax:

hotself  TEMPERATURE  ELEMENT

• TEMPERATURE - The minimum temperature that the "Self" reaction can take place. Integer between 0-99.
• ELEMENT - The name of the element this line refers to.

Neighbor

Defines interactions with neighboring (touching) elements.

Syntax:

neighbor  RATE  ELEMENT1  ELEMENT2  PROBABILITY  RESULT1  RESULT2 (PROBABILITY  RESULT1  RESULT2)...

• RATE - The probability (1.0 being 100%) of a reaction happening (per frame).
• ELEMENT1 - The name of the first element in the reaction.
• ELEMENT2 - The name of the second element in the reaction.
• PROBABILITY - The probability that the result of the reaction will be the following. Only supports 1 decimal place.
• RESULT1 - The first element this reaction results in. RESULT1 will replace ELEMENT1.
• RESULT2 - The second element this reaction results in. RESULT2 will replace ELEMENT2.

(The probability and resultX parameters may be repeated multiple times. The sum of all of the probabilities must be 1.)

HotNeighbor

Defines the minimum temperature (energy) before a specific neighbor interaction can take place.

Syntax:

hotneighbor  TEMPERATURE  ELEMENT1  ELEMENT2

• TEMPERATURE - The minimum temperature that the neighbor reaction between the listed elements can take place. Integer between 0-99.
• ELEMENT1 - The name of the first element in the reaction.
• ELEMENT2 - The name of the second element in the reaction.

Sources

Defines which elements are sources that fall from the top of the screen.

Syntax:

sources  ELEMENT  (ELEMENT)...

• ELEMENT - The name of the source element.

(The element paramenter may be specified multiple times, defining multiple sources. There should only be 1 source line per file.)

Group

Arranges the elements into different groups.

Syntax:

group  NAME  ELEMENT (ELEMENT)...

• NAME - The name of the group.
• ELEMENT - The name of the element to be added to the group.

There may be as many elements in a group as needed. Elements may be included in multiple groups if needed. Any elements not in a group will default to the "Misc" group.

Explosion

Causes reactions to explode outward.

Syntax:

explosion ELEMENT1 ELEMENT2 XSPEED YSPEED

• ELEMENT1 - The name of the first element in the reaction.
• ELEMENT2 - The name of the second element in the reaction.
• XSPEED - The maximum X-vector speed of the resultant particles. Must be less than 255.
• YSPEED - The maximum Y-vector speed of the resultant particles. Must be less than 255.

There must be a defined neighbor reaction between the two particles. When the reaction occurs, the new particles will be traveling outward at a random speed from 0 to each of the vector maximums, in either direction. Collisions are not handled until the particles return to normal after a certain amount of time.

PExplosion

Causes elements to fill a radius.

Syntax:

pexplosion ELEMENT1 ELEMENT2 DIAMETER RESULT

• ELEMENT1 - The name of the first element in the reaction.
• ELEMENT2 - The name of the second element in the reaction.
• DIAMETER - The diameter of the circle.
• RESULT - The name of the element to fill the circle.

Whenever the two elements meet, a circle around that point is formed containing the result element. It overrides anything else within the radius, so be careful.

Examples

Element

element  Fire  247  63  63  -1.000000  1.000000  0.000000  1.100000  1

Defines an element named "Fire", which "falls" up with a speed of 1.0, has a slip of 1.0, has a density of 0, and an condictivity of 1.1, meaning it gives off energy, and is a visible selection.

Neighbor

neighbor  0.9  Fire  Water  1.0  Empty  Steam

90% of the time when Fire and Water touch a reaction will happen. 100% of the time the Fire will turn to Empty and the Water will turn to Steam.

neighbor  0.9  Fire  Water  0.5  Empty  Steam  0.5  Steam  Empty

90% of the time when Fire and Water touch a reaction will happen. 50% of the time the Fire will turn to Empty and the Water will turn to Steam. The other 50% of the time the Fire will turn into Steam and the Water will turn into Empty.

HotSelf

self  0.001  Water  1.0  Steam 
hotself  50  Water

By itself the Self line means that 0.1% of the time the Water will turn to Steam. But the HotSelf line changes it to mean that the Water can only turn to Steam if it's temperature is at least 50.

HotNeighbor

Just as the HotSelf directive limits the Self reaction to only happen over a certain temperature, the HotNeighbor directive modifies the Neighbor directive.

neighbor  0.001  Saltwater  Saltwater   1.0  Salt  Steam 
hotneighbor  50  Saltwater  Saltwater

By itself the Neighbor line would mean that 0.01% of the time when Saltwater and Saltware come in contact there would be a reaction. 100% of the time that reaction would result in Salt and Steam. The HotNeighbor line changes it to mean that the reaction can only happen if the Saltwater's temperature is at least 50.

Probabilities

Fairly simple, the higher the probabilty, the more likely it is to happen. Take, for example, the self lines of Fire and Ember.

self   0.050000   Fire    1.000000   Empty
self   0.002000   Ember   1.000000   Fire 

The second item on the line is the probability. So what does it mean? The higher the number, the higher probability it has to happen; Fire turns into Empty much faster than Ember turns into Fire (25 times faster, in fact). The highest probability is 1 (100%). You can type a number higher than 1 but the game will read it as 1 because something can't happen more than 100% of the time. Every time the game refreshes itself (That's every Frame) It figures out a calculation for every single dot of element with a self line, and every single dot of element touching an element that has a neighbor reaction with it, and figures out which ones do what.

Example:

neighbor   0.200000   Plant   Water   1.000000   Plant   Plant

This means that every dot of water touching a dot of plant has a 0.2 (20%) chance of turning into plant (and the plant staying as plant). So on average every fifth dot of water touching a dot of plant will turn into plant.

Note that probabilities lower than 0.001 will not function.

Element Overview

There are three essential types of Elements. Solids, Liquids, and Gases. these are also sometimes known as Rigids, Particulates, and Gases respectively.

Solids/Rigids

The best example of a Solid is Wall. Let's look at Wall now.

element   Wall   128   128   128   0.000000   0.000000   1.000000   0.500000   1

So, just by looking at the code we know it's an element, It's called Wall, it's a kind of dark grey colour. It has no gravity, It has no slip, it's density is 1 and conductivity 0.5. It is also visible in the list.

Okay, so what makes this a Solid rather than anything else?

The Gravity - it has no gravity, so it doesn't fall

The Slip - if things ever fall through it it won't slip all over the place as it 'falls' upwards.

The Density - it has a Density of 1. This means only anything with a density higher than 1 will fall through it. So that's basically only elements specially made to fall through it will make it 'fall' upwards.

Liquids/Fluids/Particulates

There's two types of liquids/particulates; those that are Liquids, and those that are Particulates. So it's all in the Name really. Lets look at sand, a particulate:

element   Sand   238   204   128   0.900000   0.500000   0.900000   0.000000   1

The Gravity - It has a positive number for gravity, so it falls downwards (as opposed to not moving or 'falling' upwards).

The Slip - for a Liquid/Particulate, this can be anywhere between 0 and 1, although it is typically between 0.3 and 0.6. Liquids typically have less Slip than particulates.

The Density - Sand has a high Density, but not all Particulates/liquids do - Oil has a density of 0.2! Density is all about what floats on what. 'Heavy' liquids/particulates have a higher density than 'Lighter' ones. Particulates typically have a higher Density than Liquids.

Gases/Plasmas

Again, two types of Gas/Plasma: Gases, and Plasma. The difference being that all Plasmas have positive conductivity - they produce heat.

element   Fire   247   63   63   -1.000000   1.000000   0.000000   1.100000   1

The Gravity - Gases are distinguished primarily by their Negative gravity - they 'fall' upwards.

The slip - Typically high, as gases are noted for spreading out a lot.

The Density - Just like in the real world, gases have a very low density in wxSand - and plasmas even less - fire's density is 0! This is to stop gases floating up through Walls etc and to ensure that they go upwards through denser elements (eg Sand)

References

Portions of this guide have been adapted from a guild written by LE4dGOLEM.

The FSG forum link to the original guide made by the above moderator is here. Click.

The guide to making items in 4.5, made by user Bletotum of the FSG forum is here. Click.