TPTElements

Links

Mega coding reference

The gigantic reference that gives you knowledge on literally everything that you can do with The Powder Toy Lua! Improved all the time and gathered over the ages.

I suggest you use your browser's find function. The tree can get a bit verbose at times...

Notes ----- * The tree below is pretty packed with information. The doc has long lines so it is suggested that you disable word wrap. * boolint = integer that acts as a boolean (0 or 1) * mixed type means "whatever suits it there" * If not explicitly noted, all color values have limits of 0 to 255 (incl. firer/g/b, colr/g/b) and default to white. * Extension to the above: all alpha values (firea/cola) have a limit of 100 as the most opaque. * Click on all sorts of tree nodes or keys to make your address bar display the direct link to it!
(global) │ │ │
Legacy Lua APIMost, if not every, methods here are covered in other APIs. Except versions. Those are only accessible here.tpt │ │ │ ├─ version │ │ ├─ major Major game version, for example 81 │ │ ├─ minor Minor version, for example 0 │ │ └─ build Build version, for example 292 │ │ │ ├─ particle[] parts Array of particles by index, emulates sim->parts in C++ │ │ │ ├─ partsdata = nil NYI │ │ │ │ Covered under #properties below. │ ├─ el │ │ ├─ dust │ │ └─ ... │ │ │ ├─ test () Unknown │ ├─ nil drawtext (int x, int y, string text) Draws a text string only for the next frame │ │ ├─ (int x, int y, string text, int r, int g, int b) │ │ └─ (int x, int y, string text, int r, int g, int b, int a) │ │ │ ├─ int[index] create (int x, int y) Creates a new particle at (x, y) │ ├─ nil/int set_pause (boolint state) Pauses/unpauses the game (1 = paused). -1 returns the paused state. │ ├─ int toggle_pause () Toggles pause for the game. │ ├─ nil set_console (boolint state) Opens/closes the console (1 = open) │ ├─ nil log (string text) Logs to the console - precisely the thing on the right │ ├─ nil set_pressure (int x, int y, int width, int height, int value) Sets pressure for given rectangle. [wall coordinates] │ ├─ nil set_gravity (int x, int y) Sets the Newtonian Gravity for a given position. │ │ (int x, int y, int width, int height) │ │ (int x, int y, int width, int height, int value[d. 0.0]) │ │ │ ├─ nil reset_gravity_field (int x, int y) Sets gravity at (x, y) to 0.0 │ │ └─ (int x, int y, int width, int height) │ │ │ ├─ nil reset_velocity (int x, int y) Sets velocity (vx and vy) in the specified rectangle to 0 │ │ └─ (int x, int y, int width, int height) │ │ │ ├─ nil reset_spark () Converts SPRK(X) into X │ ├─ nil set_property (string property, mixed value) Sets a property of an element [affects every element] │ │ ├─ (string property, mixed value, string type) [affects elements of 1 type] │ │ ├─ (string property, mixed value, int index) [affects particle via index] │ │ ├─ (string property, mixed value, int index, string type) [affects particle via index if it is of the specified type] │ │ ├─ (string property, mixed value, int x, int y) [affects particle via position] │ │ ├─ (string property, mixed value, int x, int y, string type) [affects particle via x/y if of the specified type] │ │ ├─ (string property, mixed value, int x, int y, int width, int height) [affects region] │ │ └─ (string property, mixed value, int x, int y, int width, int height, string type) [affects region if of the specified type] │ │ │ ├─ mixed get_property (string property, int index) Returns some property of a given particle │ │ └─ (string property, int x, int y) │ │ │ ├─ nil set_wallmap (int x, int y, int value) Place or change a wall at (x, y) to (value) │ │ └─ NYI: (int x, int y, int width, int height, int value) │ │ │ ├─ int get_wallmap (int x, int y, [NYI: int width, int height]) Get the wall at [wall coordinates!] x, y │ ├─ nil set_elecmap (int x, int y, int value) Sets the sim->emap value for [wall coordinate] x, y │ │ └─ (int x, int y, [NYI:int width, int height,] int value) │ │ │ ├─ int get_elecmap (int x, int y) Returns the sim->emap value for [wall coordinate] x, y │ ├─ nil drawpixel (int x, int y) Draws a pixel for the next frame │ │ ├─ (int x, int y, int r, int g, int b) │ │ └─ (int x, int y, int r, int g, int b, int a) │ │ │ ├─ nil drawrect (int x, int y, int width, int height) Draws a hollow rect for the next frame │ │ ├─ (int x, int y, int width, int height, int red, int green, int blue) │ │ └─ (int x, int y, int width, int height, int red, int green, int blue, int alpha) │ │ │ ├─ nil fillrect (int x, int y, int width, int height) Draws a filled rect for the next frame │ │ ├─ (int x, int y, int width, int height, int red, int green, int blue) │ │ └─ (int x, int y, int width, int height, int red, int green, int blue, int alpha) │ │ │ ├─ nil drawline (int x1, int y1, int x2, int y2) Draws a line for the next frame │ │ ├─ (int x1, int y1, int x2, int y2, int red, int green, int blue) │ │ └─ (int x1, int y1, int x2, int y2, int red, int green, int blue, int alpha) │ │ │ ├─ int textwidth (string text) Find out the width of a string of text in the TPT font │ ├─ string get_name () Returns username │ ├─ nil set_shortcuts (boolint state) Enable/Disable key shortcuts │ ├─ nil delete (int index) Delete particle @ position/index │ │ └─ (int x, int y) │ │ │ ├─ nil register_step (function onTick) Add a function to be run every tick. You can have 6 of these. │ ├─ nil unregister_step (function onTick) Remove a given tick function to clean up the place. Ha! │ ├─ nil register_mouseclick (function onClick) Add a function(int mousex, int mousey, int button, int event) to run on mouse click. │ ├─ nil unregister_mouseclick (function onClick) Remove a given click function │ ├─ nil register_keypress (function onKey) Add a function to run on keypress. Arguments: char key, int keyCode, int modifierKeys, int event │ ├─ nil unregister_keypress (function onKey) Remove a given key press function. │ ├─ nil register_mouseevent = register_mouseclick │ ├─ nil unregister_mouseevent = unregister_mouseclick │ ├─ nil register_keyevent = register_keypress │ ├─ nil unregister_keyevent = register_keyevent │ ├─ string input (string title, string message) Prompt the user for input and return the data as string. Like prompt() │ ├─ nil message_box (string title, string message) Show an user some information. Really generic. Like alert() │ ├─ int get_numOfParts () Returns the particle count right now (a maximum of 235008) │ ├─ nil start_getPartIndex () Prepare getPartIndex in order to use the other two functions │ ├─ bool next_getPartIndex () True if there's a particle ID to be returned by getPartIndex │ ├─ int[index] getPartIndex () Returns the next used particle index (you can loop over this) │ ├─ nil/int hud (boolint state) Show/Hide the HUD. (1 = Show). -1 returns current state. │ ├─ nil/int newtonian_gravity (boolint state) Set Newtonian Gravity. (1 = On). -1 returns current state. │ ├─ nil/int ambient_heat (boolint state) Set Ambient Heat. (1 = On) -1 returns current state. │ ├─ nil/int active_menu (int menuID) Set active menu section. -1 returns current state. │ ├─ nil/int decorations_enable(boolint state) Toggle decorations. (1 = On) -1 returns current state. │ ├─ nil display_mode (int displayID) Set Display mode. │ ├─ nil throw_error (string text) Display a message with an error of your choosing. │ ├─ nil/int heat (boolint state) Toggle Heat. (1 = On) -1 returns current state. │ ├─ nil setfire (int strength[=1]) Set strength of fire effects │ ├─ nil setdebug (int level) Deprecated: Set debug level. 1 is what pressing D produces, higher levels used to do something │ ├─ nil setfpscap (int maxFPS[=60]) Set max FPS │ ├─ nil getscript (string author, string id) Fetch a script from the TPT Script Index. The index has no known entries as of 2013-12-27. │ ├─ nil setwindowsize (int scale[=1||2, d. 1], boolint fullscreen[=0]) Set window size (scaled and fullscreen) │ ├─ int watertest () Toggle water equalization. Returns new state. │ ├─ nil screenshot () Take a screenshot and save it as screenshot_####.png │ ├─ int/string element (string element) Return element ID from element name as string │ │ └─ (element id) Return element name as string from element ID │ │ │ ├─ string get_clipboard () Returns the current clipboard data as text │ ├─ nil set_clipboard (string data) Sets the current clipboard data as text │ ├─ nil element_func (element id, function onElement) Make a particle update function. #update_func │ │ └─ (element id, function onElement, bool replace) Replace the previous update function. │ │ │ └─ nil graphics_func (element id, function onDraw) Make an element look fancy. #graphics_funcInterface APIWe apologize for the inconvenience. │ ├ interface (ui) │ │ │ ├─ nil showWindow (Window w) Opens a Window. │ ├─ nil closeWindow (Window w) Closes a Window. │ ├─ nil addComponent (Component c) Adds a Component to the main window. │ ├─ nil removeComponent (Component c) Removes a Component from the main window. │ │ │ ├─ Component Generic class for utilities │ │ ├─ nil / bool :visible () Gets/sets whether the component is visible │ │ │ └─ (bool visible) │ │ │ │ │ ├─ nil / int,int :size () Gets/sets the component's size │ │ │ └─ (int width, int height) │ │ │ │ │ └─ nil / int,int :position () Gets/sets the component's position │ │ └─ (int x1, int y1) │ │ │ ├─ Button │ │ │ │ │ ├─ Button :new (int x, int y, int width, int height) Creates a new button. Event listener needs to be attached later. │ │ │ └─ (int x, int y, int width, int height, string text, string tooltip) │ │ ├─ nil :action (function onClick) Attaches an event listener. Arguments: Button sender │ │ ├─ nil/string :text () Gets/sets the button's text │ │ │ └─ (string text) │ │ └─ nil/bool :enabled () Get/set the button's enabled state │ │ └─ (bool state) │ │ │ ├─ ProgressBar │ │ │ │ │ │ │ │ ├─ ProgressBar :new (int x, int y, int width, int height, int progress, string status) Creates a new instance. │ │ ├─ nil/int :progress () Gets/sets the progress bar progress [0:100] -1 makes it scroll right slowly. │ │ │ └─ (int progress) │ │ └─ nil/string :status () Gets/sets the progress bar's status text. │ │ └─ (string status) │ │ │ ├─ Slider │ │ │ │ │ ├─ Slider :new (int x, int y, int width, int height) Creates a new instance. Specify the event listener and handler later on. │ │ ├─ nil :onValueChanged (function onChange) Attaches a onChanged event handler. Arguments: sender, value │ │ ├─ nil/int :value () Gets/sets its value. │ │ │ └─ (int value) │ │ └─ nil/int :steps () Gets/sets the amount of 'steps' the slider has. │ │ └─ (int steps) │ │ │ ├─ Checkbox │ │ │ │ │ ├─ Checkbox :new (int x, int y, int width, int height, [string text = ""]) Creates a new instance. │ │ ├─ nil :action (function onAction) Arguments: sender, value │ │ ├─ nil/string :text () Gets/sets its text. │ │ │ └─ (string text) │ │ └─ nil/int :checked () Gets/sets its checked state. │ │ └─ (int checked) │ │ │ │ │ ├─ Label │ │ │ │ │ ├─ Label :new (int x, int y, int width, int height, [string text = ""]) │ │ └─ nil/string :text () Gets/sets its text. │ │ └─ (string text) │ │ │ │ │ ├─ Textbox │ │ │ │ │ ├─ Textbox :new (int x, int y, int width, int height [, string text = "" [, string placeholder = "" ]]) │ │ ├─ nil :onTextChanged (function onChange) Arguments: sender │ │ ├─ nil/bool :readonly () Gets/sets its readonly state. │ │ │ └─ (string readonly) │ │ └─ nil/string :text () Gets/sets its text. │ │ └─ (string text) │ │ │ │ │ └─ Window │ │ │ ├─ Window :new (int x, int y, int width, int height) A container element for components. Set x/y to -1 to center. │ │ │ ├─ nil :onInitialized (function func) => Function listener for initialization. Callback has no arguments. │ ├─ nil :onTick (function func) => Every tick. Callback has no arguments. │ ├─ nil :onExit (function func) => When the window closes. Callback has no arguments. │ ├─ nil :onTryOkay (function func) => │ ├─ nil :onDraw (function func) => When the window is drawn. │ ├─ nil :onMouseUp (function func) => Callback args: int x, int y, int button │ ├─ nil :onMouseDown (function func) => Callback args: int x, int y, int button │ ├─ nil :onMouseMove (function func) => Callback args: int x, int y, int dx, int dy │ ├─ nil :onMouseWheel (function func) => Callback args: int x, int y, int d │ ├─ nil :onKeyPress (function func) => Callback args: int key, Uint16 character, bool shift, bool ctrl, bool alt │ ├─ nil :onKeyRelease (function func) => Callback args: int key, Uint16 character, bool shift, bool ctrl, bool alt │ ├─ nil :onFocus (function func) => When receives focus. Callback has no arguments. │ ├─ nil :onBlur (function func) => When loses focus. Callback has no arguments. │ ├─ nil :onTryExit (function func) => When user attempts to exit the window. Callback has no arguments. │ ├─ nil :addComponent (Component c) Adds a Component to the Window. │ └─ nil :removeComponent (Component c) Removes a Component from the Window.Elements APIEverything to do with elements, adding them, modifying them, ...-- │ ├ elements (elem) │ │ │ │ Particle movement types in .properties │ ├─ TYPE_PART 0x00001 │ ├─ TYPE_LIQUID 0x00002 │ ├─ TYPE_SOLID 0x00004 │ ├─ TYPE_GAS 0x00008 │ ├─ TYPE_ENERGY 0x00010 │ │ │ │ Particle properties │ ├─ PROP_CONDUCTS 0x00020 │ ├─ PROP_BLACK 0x00040 │ ├─ PROP_NEUTPENETRATE 0x00080 │ ├─ PROP_NEUTABSORB 0x00100 │ ├─ PROP_NEUTPASS 0x00200 │ ├─ PROP_DEADLY 0x00400 │ ├─ PROP_HOT_GLOW 0x00800 │ ├─ PROP_LIFE 0x01000 │ ├─ PROP_RADIOACTIVE 0x02000 │ ├─ PROP_LIFE_DEC 0x04000 │ ├─ PROP_LIFE_KILL 0x08000 │ ├─ PROP_LIFE_KILL_DEC 0x10000 │ ├─ PROP_SPARKSETTLE 0x20000 │ ├─ PROP_NOAMBHEAT 0x40000 │ │ Applies the CLNE effect: drawing with the brush over CLNE sets CLNE's ctype to something │ ├─ PROP_DRAWONCTYPE 0x80000 │ │ Doesn't allow the CLNE effect to apply with this element │ ├─ PROP_NOCTYPEDRAW 0x100000 │ │ │ │ .flags for how often update happens etcetera │ ├─ FLAG_STAGNANT 0x1 Update a bit less than usually │ ├─ FLAG_SKIPMOVE 0x2 Don't do movement checks │ ├─ FLAG_MOVABLE 0x8 │ │ │ │ .state values - element states │ ├─ ST_NONE 0 │ ├─ ST_SOLID 1 │ ├─ ST_LIQUID 2 │ ├─ ST_GAS 3 │ │ │ │ Element categories in the menu │ ├─ SC_WALL 0 │ ├─ SC_ELEC 1 │ ├─ SC_POWERED 2 │ ├─ SC_SENSOR 3 │ ├─ SC_FORCE 4 │ ├─ SC_EXPLOSIVE 5 │ ├─ SC_GAS 6 │ ├─ SC_LIQUID 7 │ ├─ SC_POWDERS 8 │ ├─ SC_SOLIDS 9 │ ├─ SC_NUCLEAR 10 │ ├─ SC_SPECIAL 11 │ ├─ SC_LIFE 12 │ ├─ SC_TOOL 13 │ ├─ SC_DECO 14 │ │ │ │ Element IDs - one for every default element, as well as Lua elements according to namespace │ ├─ DEFAULT_PT_[DUST] │ │ │ ├─ int allocate (string namespace, string name) Sets up a space for a new element. Returns new element ID. │ │ Creates key elements.NAMESPACE_PT_NAME for the ID. │ ├─ nil free (int elementID) Deletes a given element from existence. │ ├─ nil loadDefault () Deletes all new elements. Restores all default elements. │ ├─ nil/table element (int elementID) Returns a table with the element's properties, to modify and set further on │ │ └─ (int elementID, table properties) Sets _all_ the properties of an element to ones from the table. Useful for element cloning. │ └─ nil/mixed property (int elementID, string property) Returns an element's single property. │ └─ (int elementID, string property, mixed value) Sets an element's single property to value.Renderer APIEverything to do with how particles look. │ │ ├ renderer (ren) │ │ │ │ Pixel drawing modes. See Particle_Drawing_Modes.png for a quick reference. │ ├─ PMODE 0x00000FFF Bitmask to get display modes via binary AND │ ├─ PMODE_NONE 0x00000000 Invisible as in totally invisible │ ├─ PMODE_FLAT 0x00000001 Regular like Basic view │ ├─ PMODE_BLOB 0x00000002 Blurry like Blob view │ ├─ PMODE_BLUR 0x00000004 Blurry like wtrv │ ├─ PMODE_GLOW 0x00000008 Glowy like PLUT with fancy view │ ├─ PMODE_SPARK 0x00000010 Sparks used to be drawn more fancily │ ├─ PMODE_FLARE 0x00000020 Flare like BOMB │ ├─ PMODE_LFLARE 0x00000040 Large flare like DEST │ ├─ PMODE_ADD 0x00000080 If particles are stacking then adds up the colours │ ├─ PMODE_BLEND 0x00000100 Weaker than the above, does blendy magic. │ │ │ ├─ PSPEC_STICKMAN 0x00000200 Only works for STKM, shows them as STKM │ ├─ OPTIONS 0x0000F000 A bit mask for the option bit. If you're making a custom render mode just always involve this. │ ├─ NO_DECO 0x00001000 politely refuses decorations be drawn upon it (like LCRY) │ │ │ ├─ DECO_FIRE 0x00002000 enables changing the blur colour via deco │ ├─ FIREMODE 0x00FF0000 Bit mask for fire modes (below) │ ├─ FIRE_ADD 0x00100000 A pixel mode that makes it drawn like a fire particle. │ ├─ FIRE_BLEND 0x00200000 ^ with blendy magic. │ │ │ ├─ EFFECT 0xFF000000 │ ├─ EFFECT_GRAVIN 0x01000000 Enables what PRTI does (particle sucky effect), however more life/ctype magic may be needed │ ├─ EFFECT_GRAVOUT 0x02000000 ^ for PRTO │ ├─ EFFECT_LINES 0x04000000 │ ├─ EFFECT_DBGLINES 0x08000000 │ │ Render mode flags all bundled up together │ ├─ RENDER_EFFE OPTIONS | PSPEC_STICKMAN | EFFECT | PMODE_SPARK | PMODE_FLARE | PMODE_LFLARE │ ├─ RENDER_FIRE OPTIONS | PSPEC_STICKMAN | /*PMODE_FLAT |*/ PMODE_ADD | PMODE_BLEND | FIREMODE │ ├─ RENDER_GLOW OPTIONS | PSPEC_STICKMAN | /*PMODE_FLAT |*/ PMODE_GLOW | PMODE_ADD | PMODE_BLEND │ ├─ RENDER_BLUR OPTIONS | PSPEC_STICKMAN | /*PMODE_FLAT |*/ PMODE_BLUR | PMODE_ADD | PMODE_BLEND │ ├─ RENDER_BLOB OPTIONS | PSPEC_STICKMAN | /*PMODE_FLAT |*/ PMODE_BLOB | PMODE_ADD | PMODE_BLEND │ ├─ RENDER_BASC OPTIONS | PSPEC_STICKMAN | PMODE_FLAT | PMODE_ADD | PMODE_BLEND | EFFECT_LINES │ ├─ RENDER_NONE OPTIONS | PSPEC_STICKMAN | PMODE_FLAT │ │ │ │ What particle colors get drawn like - heat view or regular or whatnot │ ├─ COLOUR_HEAT 0x0000001 This is like Heat view. │ ├─ COLOUR_LIFE 0x0000002 Like Life display │ ├─ COLOUR_GRAD 0x0000004 Like Heat Gradient display │ ├─ COLOUR_BASC 0x0000008 Like Basic display │ ├─ COLOUR_DEFAULT 0x00000000 Default whatever │ │ │ ├─ DISPLAY_AIRC 0x00000001 │ ├─ DISPLAY_AIRP 0x00000002 Display air pressure │ ├─ DISPLAY_AIRV 0x00000004 Display air velocity │ ├─ DISPLAY_AIRH 0x00000008 Display air heat │ ├─ DISPLAY_AIR 0x0000000F │ ├─ DISPLAY_WARP 0x00000010 Enable gravity wells │ ├─ DISPLAY_PERS 0x00000020 Display Persistent lines │ ├─ DISPLAY_EFFE 0x00000040 │ │ │ ├─ nil/table renderModes () Get/set the render mode table │ │ └─ (table renderModeTable) │ ├─ nil/table displayModes () Get/set the display mode table │ │ └─ (table displayModeTable) │ ├─ nil/int colourMode () Get/set color mode │ │ colorMode (int colourMode) │ ├─ nil/boolint decorations () Get or set whether decorations are enabled. │ │ └─ (boolint state) │ ├─ nil/int grid () Get or set the grid display size │ │ └─ (int size) │ └─ nil/int debugHUD () Get/set whether or not debug HUD is visible. Replacement for tpt.setdebug │ └─ (int level) │ Simulation APIEverything to do with particles, pressure, heat, gravity, resetting temperature, whatnot. │ │ ├ simulation (sim) │ │ │ │ Usable in property getter/setter functions instead of property names - │ │ makes comparisons faster. │ ├─ FIELD_CTYPE │ ├─ FIELD_DCOLOUR │ ├─ FIELD_FLAGS │ ├─ FIELD_LIFE │ ├─ FIELD_TEMP │ ├─ FIELD_TMP │ ├─ FIELD_TMP2 │ ├─ FIELD_TYPE │ ├─ FIELD_VX │ ├─ FIELD_VY │ ├─ FIELD_X │ ├─ FIELD_Y │ │ │ ├─ table partNeighbours (int x, int y, int radius) Find list of particles around a center location, in a given radius. │ │ partNeighbors (int x, int y, int radius, int type) Filter for an element with a certain type too. │ ├─ nil partChangeType (int index, int type) Change particle type. Better than setting .type - │ │ some elements need special properties to work and this will set them │ ├─ nil partCreate (int x, int y, int type) Create a particle. │ ├─ nil/mixed partProperty (int index, string field) Get/set a property on a particle. Like tpt.get_property only better. │ │ └─ (int index, string field, mixed value) │ ├─ int, int partPosition (int index) Get x,y from a given particle index │ ├─ int partID (int x, int y) Get index from a pair of coordinates (x, y) │ ├─ nil partKill (int index) Delete a particle properly │ │ └─ (int x, int y) │ ├─ nil/int pressure (int x, int y) Get/set pressure at [wall coordinates] x,y │ │ ├─ (int x, int y, int value) │ │ └─ (int x, int y, int width, int height, int value) │ ├─ nil/int ambientHeat (int x, int y) Get/set ambient heat at [wall coordinates] x,y │ │ ├─ (int x, int y, int value) │ │ └─ (int x, int y, int width, int height, int value) │ ├─ nil/int velocityX (int x, int y) Get/set velocity (x) at [wall coordinates] x,y │ │ ├─ (int x, int y, int value) │ │ └─ (int x, int y, int width, int height, int value) │ ├─ nil/int velocityY (int x, int y) Get/set velocity (y) at [wall coordinates] x,y │ │ ├─ (int x, int y, int value) │ │ └─ (int x, int y, int width, int height, int value) │ ├─ nil/int gravMap (int x, int y) Get/set gravity at [wall coordinates] x,y │ │ ├─ (int x, int y, int value) │ │ └─ (int x, int y, int width, int height, int value) │ ├─ int createParts (int cx, int cy, int rx[=d. 5], int ry[=d. 5], │ │ int type[=d. selectedl], int brush[=d. circle], int flags[=d. replace flags]) │ │ Creates multiple particles (like drawing with a brush!) │ │ Set rx and ry to horizontal and vertical radius (ellipse brush). Returns how many particles were changed. │ ├─ int createLine (int x1, int y1, int x2, int y2, int rx, int ry, Create line with createParts. Returns how many particles were changed. │ │ int type[=d. selectedl], int brush[=d. circle], int flags[=d. replace flags]) │ ├─ int createBox (int x1, int y1, int x2, int y2, int type[=d. selectedl], int flags[=d. replace flags]) Filled box. Returns how many particles were changed. │ ├─ int floodParts (int x, int y, int type, int cm, int flags[=d. replace flags]) Flood fill particles. Returns how many particles were changed. │ ├─ int createWalls (int cx, int cy, int rx[=d. 0], int ry[=d. 0], int type[=d. 8]) Create walls. │ │ (wall types go from right to left, 1 for rightmost not delete). Returns how many particles were changed. │ ├─ nil createWallLine (int x1, int y1, int x2, int y2, int rx, int ry, int type[=d. 8]) Create line with createParts │ ├─ nil createWallBox (int x1, int y1, int x2, int y2, int type[=d. 8]) Wall boxes! │ ├─ int floodWalls (int x, int y, int type[=d. 8], int bm) Flood-fill walls! Returns how many particles were changed. │ ├─ int toolBrush (int x, int y, int rx, int ry, int tool, int brush[=d. circle]) Apply a tool (AIR, VACU, GRAV, HEAT) │ ├─ nil toolLine (int x1, int y1, int x2, int y2, int rx, int ry, int tool, int brush[=d. circle]) Tool brush with line │ ├─ nil toolBox (int x1, int y1, int x2, int y2, int tool, float strength[=d. 1.0]) Tool via box │ ├─ nil decoBrush (int x, int y, int rx, int ry, int r, int g, int b, int a, int tool[=d. DECO_DRAW], int brush[=d. circle]) Draw decorations │ ├─ nil decoLine (int x, int y, int rx, int ry, int r, int g, int b, int a, int tool[=d. DECO_DRAW], int brush[=d. circle]) │ ├─ nil decoBox (int x1, int y1, int x2, int y2, int r, int g, int b, int a, int tool) Draw a box of decorations. │ ├─ nil decoColor () Get/Set currently selected deco colour (0xAARRGGBB) │ │ └─ = nil decoColour (int colour[=d. 0xFFFF0000]) │ ├─ nil clearSim () Clear everything on the save │ ├─ nil resetTemp () Resets heat of every particle to room temperature (optionally, only metals et al) │ │ └─ (boolint onlyConductives) │ │ │ ├─ nil resetPressure () Resets pressure everywhere, or at (x, y), or as a box │ │ ├─ (int x, int y) │ │ └─ (int x1, int y1, int width, int height) │ │ │ ├─ string saveStamp (int x, int y, int width, int height) Saves a stamp and returns its cryptic name │ ├─ nil/int loadStamp (mixed id, int x, int y) Loads a stamp by its cryptic name and places it at x, y. │ │ The ID can either be char[10] or integer. 1 if not OK, nil otherwise. │ ├─ nil loadSave (int saveID, int timehistory) Loads a save or its previous variant at the time (in exact seconds!) it was saved. │ ├─ nil/int getSaveID () Returns the current save's ID. │ ├─ int, int adjustCoords (int x, int y) Set zoom window coordinates to here │ ├─ nil/int prettyPowders () Gets/Sets the powder noise thing │ │ └─ (boolint state) │ ├─ nil/int gravityGrid () Gets/Sets the gravity dot thing │ │ └─ (boolint state) │ ├─ nil/int edgeMode () Gets/Sets the edge mode. 0 = Void. 1 = Solid. │ │ └─ (int mode) │ ├─ nil/int gravityMode () Gets/Sets gravity mode. Vertical, Radial, Off, in some order. │ │ └─ (int mode) │ ├─ nil/int airMode () Gets/Sets the air mode. On, No Velocity, No Pressure, No Update, Off in some order. │ │ └─ (int mode) │ ├─ nil/boolint waterEqualisation () Gets/Sets water equalization. │ │ └─ = waterEqualization (boolint state) │ ├─ nil/int ambientAirTemp () Gets/Sets Ambient Heat mode's air temperature. Default: 293.15 │ │ └─ (int temp) │ │ │ ├─ nil/int can_move (int src, int dst) Gets/Sets what happens when element with ID (src) and element with ID (dst) try and move through each other │ │ └─ (int src, int dst, int new_value) Similar to C++ can_move[src][dst] - check out Simulation.cpp │ │ 0 = no move / bounce back, eg AMTR trying to move onto DMND │ │ 1 = swap particle locations, eg BHOL swaps elements into itself and then eats them │ │ 2 = two particles in the same space, eg two energy particles crossing │ │ 3 = other/handled elsewhere, eg PHOT trying to move into LCRY is actually handled in some update function │ │ │ ├─ int elementCount (element type) Returns how many particles have this type on the screen. │ ├─ iter parts () Returns an iterator returning existing element indexes which you can for index in sim.parts() over. │ ├─ int16 pmap (int x, int y) Returns the sim->pmap entry for a given location. The entry looks like index >> 8 | type │ └─ iter neighbours (int x, int y, int rx, int ry) Returns an object which you can for..in over, returning neighbor particles. │ └─ = neighbors │ Bit APIBecause Lua doesn't have one. │ └ bit │ ├─ int tobit (int input) Normalize for binary operations. bit.* functions do it already. ├─ string tohex (int input, int length) Generate a hex string from the input. │ ├─ int bnot (int input) Performs bitwise NOT (~input) ├─ int band (int... input) Performs bitwise AND (input&input) over all arguments. ├─ int bor (int... input) Performs bitwise OR (input|input) over all arguments. ├─ int bxor (int... input) Performs bitwise XOR (input^input) over all arguments. │ ├─ int lshift (int input, int count) Performs a leftwards bit shift (input << count). ├─ int rshift (int input, int count) Performs a rightwards bit shift (input >> count). ├─ int arshift (int input, int count) Performs a rightwards arithmetic bit shift (input >>> count). │ ├─ int rol (int input, int count) Rotates a bit right by count bits. ├─ int ror (int input, int count) Rotates a bit right by count bits. │ └─ int bswap (int input) Swaps endianness of the number.
Lua Property API ---------------- An element has many properties as seen above in the tpt.parts[] array definition. I've copied the list below for reference. Elements ~~~~~~~~ * Check out the properties reference for what each of these does. tpt.el.[inst].* │ ├─ char[4] name ├─ int color ├─ float advection ├─ float airdrag ├─ float airloss ├─ float loss ├─ float collision ├─ float gravity ├─ float diffusion ├─ float hotair ├─ int falldown ├─ int flammable ├─ int explosive ├─ boolint meltable ├─ int hardness ├─ boolint menu ├─ boolint enabled ├─ int weight ├─ int menusection ├─ float heat ├─ int hconduct ├─ int state ├─ int properties └─ string description Element transitions - check out #transitions tpt.eltransition.[inst].* │ ├─ presHighValue ├─ presHighType ├─ presLowValue ├─ presLowType ├─ tempHighValue ├─ tempHighType ├─ tempLowValue └─ tempLowType All sorts of properties - check out #properties elements.property(* │ ├─ string Name ├─ int Colour/Color ├─ boolint MenuVisible ├─ int MenuSection ├─ float Advection ├─ float AirDrag ├─ float AirLoss ├─ float Loss ├─ float Collision ├─ float Gravity ├─ float Diffusion ├─ float HotAir ├─ int Falldown ├─ boolint Flammable ├─ int Explosive ├─ boolint Meltable ├─ float Hardness ├─ int Weight ├─ int Temperature ├─ int HeatConduct ├─ string Description ├─ int State ├─ int Propertieselement transition related stuff - melting, freezing, pressure ... ├─ int LowPressure ├─ element LowPressureTransition ├─ int HighPressure ├─ element HighPressureTransition ├─ int LowTemperature ├─ element LowTemperatureTransition ├─ int HighTemperature ├─ element HighTemperatureTransition ├─ function(int index, int x, int y, int surround_space, int nt) Update └─ function(int index, int colr, int colg, int colb) Graphics Particles ~~~~~~~~~ (particle) │ ├─ int type which element type is this? ├─ int life commonly used on various elements to induce timed death - can be set to automatically decrease ├─ int ctype commonly used as the "underlying type" of various elements like SPRK's original metal ├─ float x the element's X coordinate ├─ float y the element's X coordinate ├─ float vx the element's horizontal speed (>0 = right, <0 = left) ├─ float vy the element's vertical speed (>0 = right, <0 = left) ├─ float temp the element's temperature in kelvins (displayed - 273.15) ├─ float pavg[2] magic ├─ int flags special flags that aren't saved - stuff like FLAG_STAGNANT ├─ int tmp generic use integer for an element - used lots for usage modes like FILT filter modes ├─ int tmp2 another generic use integer for an element - things like EXOT use it as colour storage └─ unsigned int dcolour the colour of the decorations drawn onto it: 0xAARRGGBB
Properties ----------

float Advection

How much the particle is pushed 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.

float AirDrag

How much air the particle "drags" along with itself when moving. CFDS is a magical constant that makes airdrag properly work with different pressure grid sizes. Thus the definition should always be multiplied by that.

For example,

AirDrag = 0.004f * CFDS;

float AirLoss

How much it reduces velocity. 1 for no effect, 0 for full effect.

Note: TTAN is not powered by this and this means you can't make TTAN simply by setting this value to zero. Pressure can jump around a bit, too!

float Collision

When this particle hits something, this value is used to determine new velocity.

int Colour

This will be the particle's colour in Basic render mode as well as the element button's. It has a format similar to CSS colours: `0xRRGGBB` where every letter specifies which colour the byte specifies, so 0xFF0000 would have exactly 255/255 tones red, and 0 tones both green and blue.

You can set it in C++ by using the PIXPACK preprocessor macro:

Colour = PIXPACK(0x333333);

...and in Lua by using elements.property with the same hexadecimal value.

const char* (or string) Description

It's the text that the element shows when you put your mouse over its selection button! Meant to be an element's description semantically speaking, however. So use it as that :)

Description = "Broken Coal. Heavy particles. See COAL";

float Diffusion

poke boxmein to add text here

boolint Enabled

If the element is enabled to be used in-game at all, use a value of 1. You can use a value of 0 to disable elements softly while still breaking every save in existence. In general, keep it as 1.

int Explosive

Sets default behaviour on if and how this element explodes. It works kind of like C4 does: like burning except it spreads around very quickly, often in a single tick, creating more pressure than normal. You can obviously do this in your update code though...

0 = no default explosion behavior. 1 = Explodes with fire. 2 = Explodes with >2.5 pressure as well as fire.

int Falldown

Sets what kind of default moving code this particle will use.

0 = Solid (or rather, no 'regular' movement!) 1 = Powder 2 = Liquid

int Flammable

How well this particle catches on fire. FIRE has a basic reaction in which it checks how flammable nearby particles are and uses that as a number to say how quickly and how likely this particle will turn into fire. Particles are entirely nonflammable at 0 and from there on become increasingly more flammable.

int (*Graphics) (GRAPHICS_FUNC_ARGS)

Allows you to specify a function to change the particle's color and various effects applied to it.

For how this works in Lua, you are passed four variables and expected to return a dozen more.

Parameters: index, colr, colg, colb Return values: cache, pixel_mode, cola, colr, colg, colb, firea, firer, fireg, and fireb.

The cache variable tells the graphics renderer not to call this function any- more, since the color won't change anyway. Aside that, all properties are the same as what C++ should have them.

In C++ however, you are passed pointers with all the values to be returned. Bluntly assign to them as you would to any other pointer.

*colr = 255;

Also check out all the different arguments you will get as your function parameters.

#define GRAPHICS_FUNC_ARGS Renderer * ren, Particle *cpart, int nx, int ny, int *pixel_mode, int *cola, int *colr, int *colg, int *colb, int *firea, int *firer, int *fireg, int *fireb ren contains a reference to your local neighbourhood renderer, cpart your current particle (you can do stuff like cpart->life!), nx and ny to the particle's actual position (x and y), pixel_mode to any extra effects the pixel may be subject to, cola, colr, colg and colb represent the element's Colour property (alpha, red, green and blue) at first, but should be modified to the end result's colour, firea, firer, fireg and fireb represent the fiery glow's colour, if the element has a fiery glow pixel mode applied, as alpha, red, green and blue.

float Gravity

This determines how strongly gravity affects this particle. ANAR has this set as negative for example!

// No effect Gravity = 0f; // Floats upwards at normal gravity's speed Gravity = -1f; // Floats downwards almost at normal gravity's speed Gravity = 0.999f;

int Hardness

How well acid affects this particle. The bigger this value is, the better acid is at eating through it.

int HeatConduct

Shows how well this particle transfers heat. In tpt.el.*, it's called hconduct instead of heatconduct. You can use a value from 0 (none at all) to 255 (really good).

INSL and FRME have this as 0.
INSL/INST/HSWC and a few more have 251.

float HotAir

How much the particle increases the pressure around itself by, in order to simulate heating air around (this was made way before ambient heat). Another property that's mostly only used for gasses, but VENT/VACU have theirs at (-)0.010f. An extremely small number, sometimes as small as 0.000001f

Note: ICE has this as a negative value - it slightly reduces pressure!

string Identifier

Element's name on the Lua API. You usually set it to <NAMESPACE>_PT_<ELEMENTNAME>, in order to tell the executable what your element ID variable will be called inside Lua.

An example value could be:

Identifier = "DEFAULT_PT_BCOL";

In Lua scripting, you can set it with:

local element_id = elements.allocate("DEFAULT", "BCOL")

float Loss

How much speed the particle loses every frame. 1 means that no velocity is removed and anything less means that more velocity will be removed.

int Meltable

Does this particle melt into LAVA? (I'm not sure about the threshold just yet.)

boolint MenuSection

Which menu section it's under.

Menu section constants can be found under SC_* in the reference tree.

boolint MenuVisible

Sets or gets whether this element gets placed into a menu. You can still access the element without it being in the menu via alt-click sampling. A value of 1 means that the item will have a button placed into some menu.

string(4) Name

This is the element's name outside the Lua API. It's what will be drawn on top of the element's button and what one will use to refer to the element in the exclamation-point command interface.

An example value could be:

Name = "BCOL";

int Properties

Every kind of element property other than the ones above. It's just a bunch of special flags that enable or disable things relating to this element. Some of the things include whether you can 'paint' ctypes onto this element, whether it can be 'painted' as a ctype onto other elements, stuff to do with neutron movements, etc.

If you want to use multiple at the same time, apply binary OR to them! Easy enough, right?

Properties = TYPE_PART | PROP_NEUTPENETRATE;

int State

It's just a flag to tell which state the element's in right now, or even if it doesn't have a state. The only place I've seen it used so far is STKM figuring out which particles it can spark...?

(elements.)ST_SOLID = Solid (elements.)ST_LIQUID = Liquid (elements.)ST_GAS = Gas (elements.)ST_NONE = None of the above. State = ST_SOLID;

float Temperature

The spawning temperature of this element. If you draw or create it in a standard way then this is the heat the element will have once it's created. The value's in Kelvin though, so you'll have to convert if you don't like it. You could also just do addition if you're in C++ or even Lua, it gets optimized out.

// #define R_TEMP 22.0f Temperature = R_TEMP + 273.15f + 0.00f;

int (*Update) (UPDATE_FUNC_ARGS)

This is a function that will be called for every particle once per tick. You can do various things here with the simulation and particles around you, and so this is an useful function for all sorts of updating purposes.

You can see the various objects you can access from the function (and others through them):

(in C++):

#define UPDATE_FUNC_ARGS Simulation* sim, int index, int x, int y, int surround_space, int no_type, Particle *parts, int pmap[YRES][XRES]

(in Lua):

number index, number x, number y, number surround_space, number nt

Once you define your function, the assignment to this property is very simple:

Update = &Element_BCOL::update;

int Weight

Particle weight. A looong time ago there used to be a table that kept track of what element sank under which and which it stayed on top of.

Below is an estimate to which range TPT's default elements' weights belong:

1 = gasses. 2 = very light powders. DUST? 0-49 = liquids. 50-99 = default powders. 100 = solids. -1 = energy particles (PHOT/NEUT/ELEC/PROT).
Pixel modes
-----------

There's a handy pixel mode image on the wiki, so definitely check it out!

Also note that PRTI/PRTO effects cannot be applied without some witchcraft applied to the ctype and life values of the element. Check out Renderer::render_parts if really interested.

pixel_mode
  │
  │ -- Prevents anything from being drawn. Kinda like WARP.
  ├─ PMODE_NONE     0x00000000
  │ -- Draw an opaque pixel, aka transparency is not applied.
  ├─ PMODE_FLAT     0x00000001
  │ -- Adds a blobby effect, like you were using blob (5) display mode
  ├─ PMODE_BLOB     0x00000002
  │ -- Liquids in Fancy display apply this. Adds a blur and makes the pixels
  │ -- remain sharp as well.
  ├─ PMODE_BLUR     0x00000004
  │ -- Plain ol' glow. Stuff like ARAY (In fancy display) use this.
  ├─ PMODE_GLOW     0x00000008
  │ -- Kinda dim PMODE_FLARE - GBMB uses this - beams running horizontally and
  │ -- vertically + glow to emphasize brightness
  ├─ PMODE_SPARK    0x00000010
  │ -- Regularly bright PMODE_FLARE - BOMB uses this - beams running
  │ -- horizontally and vertically
  ├─ PMODE_FLARE    0x00000020
  │ -- Large and super bright PMODE_FLARE - DEST is the only thing using this.
  ├─ PMODE_LFLARE   0x00000040
  │ -- This adds some magic to the equation to make multiple layered particles
  │ -- add up to be brighter than one particle alone.
  ├─ PMODE_ADD      0x00000080
  │ -- Even more magical than PMODE_ADD, somehow better for OpenGL?
  ├─ PMODE_BLEND    0x00000100
  │ -- Something very STKM specific that won't work anywhere except on STKM
  ├─ PSPEC_STICKMAN 0x00000200
  │ -- Disables decorations on this element (LCRY does this as well as some
  │ -- magic to paint itself colours)
  ├─ NO_DECO        0x00001000
  │ -- The fire/blurriness colors get decorations too. Gasses might use this.
  ├─ DECO_FIRE      0x00002000
  │ -- Adds fire colors around the element (although weak ones - LAVA and LIGH
  │ -- lines use that)
  ├─ FIRE_ADD       0x00010000 -- adds a weak fire effect around the element
  │ -- (ex. LAVA/LIGH)
  │ -- Adds more impressive fire colors around the element. Gasses use this
  │ -- for their coloring.
  ├─ FIRE_BLEND     0x00020000
  │ -- PRTI/PRTO effect flags: note that they need magic life/ctype
  │ -- variables!
  ├─ EFFECT_GRAVIN  0x01000000
  └─ EFFECT_GRAVOUT 0x02000000
Game of Life IDs
-----

Game of Life used to be separate elements in The Powder Toy, but has been replaced with a single element called LIFE. The kind of cellular automaton a particle of LIFE represents is determined by the ctype property. Here's a quick overview of the available ctypes for LIFE:

- GOL 0 - HLIF 1 - ASIM 2 - 2x2 3 - DANI 4 - AMOE 5 - MOVE 6 - PGOL 7 - DMOE 8 - 34 9 - LLIF 10 - STAN 11 - SEED 12 - MAZE 13 - COAG 14 - WALL 15 - GNAR 16 - REPL 17 - MYST 18 - LOTE 19 - FRG2 20 - STAR 21 - FROG 22 - BRAN 23

Good luck coding! Hope this will come in handy. ~boxmein

Last Modified: Sun Jan 17 2016 03:33:03 GMT+0200 (EET)