Difference between revisions of "Lua"

From The Powder Toy
Jump to: navigation, search
m (1 revision)
(Add tpt.version and DEBUG_ constants)
 
(85 intermediate revisions by 32 users not shown)
Line 1: Line 1:
You may open the Lua Console by hitting the ''[`]'' key. (Also known as the tilde ''[~]'' key) [http://img97.imageshack.us/img97/6811/tildekey1.jpg| click here to view key]
+
{{Languages|Lua}}
  
Or ''[¬]''.
+
''This page describes an old version of TPT's Lua API, most of which is unsuitable for new scripts. For the new API, see [[Powder Toy Lua API]].''
 +
 
 +
You may open the Lua Console by hitting the ''[`]'' key. (Also known as the tilde ''[~]'' key, or the ''[¬]'' key) [http://www.bittbox.com/wp-content/uploads/2007/12/tilde_illustrator_1.jpg click here to view key]
  
 
----
 
----
  
'''BEFORE YOU FRET, YOU CAN STILL USE OLD COMMANDS. JUST PLACE AN '!' (without quotes) BEFORE THE COMMAND IN THE CONSOLE'''
+
You may be used to this style of console commands: ''!set type dust metl''. This can be useful, but Lua is an entire programming language that can do much more powerful things. The equivalent command in TPT's Lua is ''tpt.set_property("type", "metl", "dust")'' (see [[Lua#tpt.set_property]] )
 +
 
 +
This page describes the TPT Lua API, not the Lua language itself. But, you may research Lua on your own. If you're a beginner, look at this: http://www.lua.org/pil/ . If more advanced, a list of all the functions is here: http://www.lua.org/manual/5.1/
 +
 
 +
Also, FeynmanTechnologies has written a tutorial on some of the most basic Lua features here: https://powdertoy.co.uk/Discussions/Thread/View.html?Thread=17801
 +
 
 +
The Lua Console provides the ability to create scripts using Lua, a very simple scripting language. With the ability to script with Lua, users are now able to create simple modifications to the game without editing source code. For information on how to run scripts, see [[Running Lua Scripts]]
 +
 
 +
=  Lua API  =
 +
The Powder Toy exposes the following methods to the Lua API:
 +
 
 +
==  Game  ==
 +
 
 +
===  tpt.set_pause  ===
 +
 
 +
<code>tpt.set_pause(number state)</code>
 +
 
 +
Sets the paused state of the game.
 +
 
 +
The number argument is either 0 or 1, where 1 means the game will be paused, and 0 will unpause the game. If you don't pass in any arguments, the command will return an integer, either 0 or 1, about whether the game is currently paused.
  
''!set type dust metl''  
+
'''Examples''':
  
The equivalent command in TPT's Lua is ''tpt.set_property("type", "metl", "dust")'' (see http://powdertoy.co.uk/Wiki.html?id=lua#tptset_property )
+
Pause the game: <code>tpt.set_pause(1)</code>
  
But, try to learn the Lua interface. It may be a lot more useful to you than you think. ''(This wiki does not teach you the Lua language. This is simply an API. But, you may research Lua on your own http:''www.lua.org/manual/5.1/ )//
+
Get if the game is paused currently: <code>tpt.set_pause() == 1</code>
  
----
+
===  tpt.set_console  ===
 +
 
 +
<code>tpt.set_console(number state)</code>
 +
 
 +
Set the visibility state of the console.
 +
 
 +
The number argument can be either 0 or 1, where 1 means the console will be opened, and 0 will close the console. If you don't pass in any arguments, the command will return an integer, either 0 or 1, about whether the console is currently opened.
 +
 
 +
'''Examples''':
 +
 
 +
Open the console: <code>tpt.set_console(1)</code>
 +
 
 +
Get if the console is currently open: <code>tpt.set_console() == 1</code>
 +
 
 +
===  tpt.set_shortcuts  ===
 +
 
 +
'''This function is REMOVED in TPT 94.0'''
 +
 
 +
<code>tpt.set_shortcuts(number state)</code>
 +
 
 +
Set whether one can use keyboard shortcuts such as making a stamp or opening the console or changing view modes.
 +
 
 +
The number argument can be either 0 or 1, where 1 means keys will be enabled, and 0 will disable key shortcuts. If you don't pass in any arguments, the command will return an integer, either 0 or 1, about whether key shortcuts are enabled right now.
 +
 
 +
When you want to make a key command which uses some other key, don't use this, rather disable default behavior for that one key only by returning false from inside your callback.
 +
 
 +
'''Examples''':
 +
 
 +
Disable keyboard shortcuts: <code>tpt.set_shortcuts(0)</code>
 +
 
 +
Get if keyboard shortcuts are currently disabled: <code>tpt.set_shortcuts(-1) == 1</code>
 +
 
 +
===  tpt.set_gravity  ===
 +
 
 +
<code>tpt.set_gravity(number x, number y, number width, number height, number value)</code>
 +
 
 +
Sets Newtonian Gravity at a position or area to some value.
 +
 
 +
'''Default values:'''
 +
 
 +
'''x''' = 0<br>'''y''' = 0<br>'''width''' = XRES/CELL = 612 / 4 = 153<br>'''height''' = YRES/CELL = 384 / 4 = 96<br>'''value''' = 0
 +
 
 +
'''Examples''':
 +
 
 +
Reset gravity in the cell at point (150, 150): <code>tpt.set_gravity(150 / sim.CELL, 150 / sim.CELL)</code>
 +
 
 +
Reset gravity from (100,100) to (300,300): <code>tpt.set_gravity(100 / sim.CELL, 100 / sim.CELL, 200 / sim.CELL, 200 / sim.CELL) </code>
 +
 
 +
Set the entire stage's gravity to 1000: <code>tpt.set_gravity(nil, nil, nil, nil, 1000)</code>
 +
 
 +
===  tpt.reset_gravity_field  ===
 +
 
 +
<code>tpt.reset_gravity_field(number x, number y, number width, number height)</code>
 +
 
 +
Thoroughly resets Newtonian gravity on a given point.
 +
 
 +
Instead of tpt.set_gravity which only modifies <code>sim-&gt;gravmap</code>, this code modifies <code>sim->gravp</code>,<code>sim->gravx</code> and <code>sim->gravy</code>. Mmm, gravy.
 +
 
 +
'''Default values:'''
 +
 
 +
'''x''' = 0<br>'''y''' = 0<br>'''width''' = XRES/CELL = 612 / 4 = 153<br>'''height''' = YRES/CELL = 384 / 4 = 96
 +
 
 +
'''Examples''':
 +
 
 +
Thoroughly reset gravity in the cell at point (150, 150): <code>tpt.reset_gravity_field(150 / sim.CELL, 150 / sim.CELL)</code>
 +
 
 +
Reset gravity from (100, 100) to (300,300): <code>tpt.reset_gravity_field(100 / sim.CELL, 100 / sim.CELL, 200 / sim.CELL, 200 / sim.CELL) </code>
  
The new Lua Console now provides the ability to create scripts using Lua, a very simple scripting language.
+
===  tpt.set_pressure  ===
  
With the ability to script with Lua, users are now able to create simple modifications to the game without editing source code easily.
+
<code>tpt.set_pressure(number x, number y, number width, number height, number value)</code>
  
==  = Quick Introduction to Scripts =  ==
+
Sets or resets pressure in the pressure map to some pressure. I sometimes imagine how much I can repeat the word "pressure" inside a sentence before it becomes gibberish.
===  How to run a script  ===
 
To run a script, place the .lua file in the root folder of powder toy (where the powder toy executable is located). Open the console (see below) and type in '''dofile("filename.lua")''' where "filename.lua" is the the script you wish to run.
 
  
===  Variable Types  ===
+
'''Default values:'''
<ins>The different variable types are:</ins>
 
  
 +
'''x''' = 0<br>'''y''' = 0<br>'''width''' = XRES/CELL = 612 / 4 = 153<br>'''height''' = YRES/CELL = 384 / 4 = 96<br>'''value''' = 0
  
* ''''string''''
+
'''Examples:'''
  
Represents a word, character, or phrase. ''''string'''' variables must begin and end with double-quotes. (''"'')
+
Reset pressure everywhere: <code>tpt.set_pressure()</code>
  
'''Example:''' ''local str = "This is a string variable."''
+
Set pressure of cell at (100, 100) to 200: <code>tpt.set_pressure(100 / sim.CELL, 100 / sim.CELL, 1, 1, 200)</code>
  
----
+
Set pressure everywhere to 200: <code>tpt.set_pressure(nil,nil,nil,nil,200)</code>
  
* ''''number''''
+
===  tpt.reset_velocity  ===
  
Represents a number. Numbers may be floating-point or fixed-point types (meaning they may have decimals [floating-point] or may be numbers with no fraction [fixed-point].)
+
<code>tpt.reset_velocity(number x, number y, number width, number height)</code>
  
'''Example:''' ''local num = 1234''
+
Sets velocity (both x and y) in a given region or point to 0.
  
----
+
'''Default values:'''
  
* ''''boolean''''
+
'''x''' = 0<br>'''y''' = 0<br>'''width''' = XRES/CELL = 612 / 4 = 153<br>'''height''' = YRES/CELL = 384 / 4 = 96
  
Represents a switch that is either on (true) or off (false).
+
'''Examples:'''
  
'''Example:''' ''local bool = true''
+
Reset velocity everywhere: <code>tpt.reset_velocity()</code>
----
 
  
* ''''function''''
+
Reset velocity in the cell at point (100,100): <code>tpt.reset_velocity(100 / sim.CELL, 100 / sim.CELL, 1, 1)</code>
  
Represents a method or function in lua.
+
===  tpt.hud  ===
  
'''Example:''' ''function func(arguments)''
+
<code>tpt.hud(number state)</code>
  
'''NOTE:''' Functions that use a ''''function'''' as an argument do not include the () at the end. Only the name must be given.
+
Set HUD visibility.
  
----
+
Does the same thing as pressing the H key normally. The number argument can be either 0 or 1, where 1 will show the HUD, and 0 will hide the HUD. If you don't pass in any arguments, the command will return an integer, either 0 or 1, about whether the HUD is visible right now.
  
* ''''table''''
+
===  tpt.newtonian_gravity  ===
  
Tables are a group of variables. Tables can also act as an array. Tables can carry any type of variables, and can even mix different types of variables.
+
<code>tpt.newtonian_gravity(number state)</code>
  
'''Example:''' ''local tbl = {}''
+
Sets Newtonian Gravity on and off.
  
This creates a blank table.
+
Does the same thing as Ctrl+N in normal gameplay.  
  
 +
The number argument can be either 0 or 1, where 1 will enable Newtonian Gravity, and 0 will disable Newtonian Gravity. If you don't pass in any arguments, the command will return an integer, either 0 or 1, about whether Newtonian Gravity is turned on at the given moment.
  
 +
===  tpt.ambient_heat  ===
  
'''Example:''' ''local tbl = {1, 2, 3, "string"}''
+
<code>tpt.ambient_heat(number state)</code>
  
Creates a table with the elements 1, 2, 3 and "string".
+
Toggles Ambient Heat state.
  
You can call these variables in this manner:
+
The number argument can be either 0 or 1, where 1 will enable Ambient Heat, 0 will disable it. If you don't pass in any arguments, the command will return an integer, either 0 or 1, about whether Ambient Heat is turned on at the given moment.
  
 +
===  tpt.decorations_enable  ===
  
tbl[1] --returns 1
+
<code>tpt.decorations_enable(number state)</code>
tbl[2] --returns 2
 
tbl[3] --returns 3
 
tbl[4] --returns "string"
 
  
 +
Toggle drawing decorations.
  
 +
The number argument can be either 0 or 1, where 1 will enable decorations, and 0 will disable them. If you don't pass in any arguments, the command will return an integer, either 0 or 1, about whether decorations are turned on at the given moment.
  
'''Example:'''
+
===  tpt.heat  ===
  
local tbl = {}
+
<code>tpt.heat(number state)</code>
tbl.x = 7
 
tbl.y = 5
 
tbl.str = "this is a string"
 
tbl.sqr = function(v) return v * v end
 
  
Creates a table with the variables x, y, str, and the function sqr.
+
Toggles Heat Simulation.  
  
You can call these variables in this manner:
+
The number argument can be either 0 or 1, where 1 will enable heat, and 0 will disable it. If you don't pass in any arguments, the command will return an integer, either 0 or 1, about whether heat is turned on at the given moment.
  
tbl.x --returns 7
+
It's usually wise not to disable this, as there are practically no saves left that need the compatibility mode in order to work. Nevertheless this option exists.  
tbl.y --returns 5
 
tbl.str --returns "this is a string"
 
tbl.sqr(2) --returns 4 (remember this is a function that takes 'v' and squares it. )
 
  
----
+
===  tpt.active_menu  ===
  
* ''''object''''
+
<code>tpt.active_menu(number menu)</code>
  
Acts as a wildcard. It can be represented as any of the above, but this does '''not''' mean it '''can''' be any type, it depends on the function.
+
Changes activated menu. If you don't pass in any arguments, the command will return the currently active menu.
  
===  General Arguments  ===
+
The menu IDs are detailed here: [[Element_Properties#Menu_sections]]
<ins>The arguments given here are general, here are some examples:</ins>
 
  
 +
Example: <code>tpt.active_menu(elem.SC_EXPLOSIVE)</code>
  
''''string'' '''property'''''
+
===  tpt.menu_enabled  ===
  
This is to specify what property of a particle to change. REMINDER: This is a ''''string'''' variable, meaning it is a word that must begin and end with double-quotes. (''"'')
+
<code>
The different available properties are:
+
boolean tpt.menu_enabled(number menuID)
  
''"type"
+
tpt.menu_enabled(number menuID, boolean enabled)
 +
</code>
  
"life"
+
Returns true if a menu section is enabled. 
  
"ctype"
+
If provided a boolean, will set if a menu section is enabled.
  
"temp"
+
===  tpt.num_menus  ===
  
"tmp"
+
<code>
 +
number tpt.num_menus()
  
"vx"
+
number tpt.num_menus(boolean onlyEnabled)
 +
</code>
  
"vy"
+
Returns the number of menus.
  
"x"
+
The optional onlyEnabled boolean is true by default.
  
"y"''
+
===  tpt.display_mode  ===
  
Any other given strings will result with an invalid property error.
+
<code>tpt.display_mode(number display)</code>
  
----
+
Changes activated display mode.
  
''''object'' '''value'''''
+
There's 11 display modes, detailed here [[https://github.com/ThePowderToy/The-Powder-Toy/blob/f54189a97f6d80181deb4f6d952ccf10f0e59ccf/src/graphics/Renderer.cpp#L2587-L2644]]<br>
 +
Note that the order of display modes is shifted by 1 making velocity mode first and alternative velocity last.
  
What you are setting the current property to. Since this is an '''object''' variable, it's type will depend on the function.
+
'''Display Modes'''
  
----
+
0 = Velocity<br>
 +
1 = Pressure<br>
 +
2 = Persistent<br>
 +
3 = Fire<br>
 +
4 = Blob<br>
 +
5 = Heat<br>
 +
6 = Fancy<br>
 +
7 = Nothing<br>
 +
8 = Heat Gradient<br>
 +
9 = Life Gradient<br>
 +
10 = Alternate Velocity<br>
  
''''string'' '''type'''''
+
===  tpt.setfpscap  ===
  
A ''''string'''' which is the code-name of an element "dust" "watr" "spng".
+
<code>tpt.setfpscap(number fpscap)</code>
  
----
+
Changes the upper FPS limit the program will run at. This value is '''60 by default.'''
''''number'' '''index'''''
 
  
A specific particle number by it's index.
+
Don't set it too high, it'll eat all your CPU speed and make the game too responsive! Don't also set it too low, since UI and everything related to it uses the same FPS, so you'll find buttons and stuff not working.
  
----
+
If you don't pass in any arguments, it will return the current fps cap. If you set the fpscap to 2, this will uncap the framerate.
  
''''number'' '''state'''''
+
=== tpt.setdrawcap ===
  
0 or 1, 0 for off, 1 for on.
+
Changes the rate that particle graphics and the UI render to the screen. This is separate from the fpscap, which only affects the simulation. The drawcap allows TPT to skip drawing every frame. This may increase the framerate in some instances.
  
----
+
The default is set to the maximum refresh rate of all attached monitors.
  
''''number'' '''Width''''' and ''''number'' '''Height'''''
+
===  tpt.setfire  ===
 +
Changes the strength of the game's glowing effects. tpt.setfire(1) is default.
  
Represent a rectangle.
+
<code>tpt.setfire(number strength)</code>
  
----
+
===  tpt.setwindowsize  ===
  
''''number'' '''x''''' and ''''number'' '''y'''''
+
<code>tpt.setwindowsize(number scale, number fullscreen)</code>
  
Represents a 2-Dimensional coordinate.
+
Changes a few special properties as to what size the game renders at.
  
----
+
Scale is a multiplier by which every pixel shall get multiplied at, currently it can either be 1 (612x384) or 2 (1224x768).
  
''''string'' '''text'''''
+
Full screen is a toggle (0 or 1) that enables "kiosk mode", which basically scales the game up to fill the screen and makes the rest of the edge black.
  
Represents text
+
===  tpt.toggle_pause  ===
 +
Toggle pause.
  
----
+
<code>tpt.toggle_pause()</code>
  
''''number'' '''toggle'''''
+
===  tpt.watertest  ===
 +
'''REPLACED by simulation.waterEqualisation'''
  
Represents either 1 for on or 0 for off
+
Toggles water equalization.
 +
Returns current state.
  
----
+
<code>number tpt.watertest()</code>
  
''''number'' '''menu'''''
+
===  tpt.perfectCircleBrush  ===
 +
Returns true if perfect circle brush is enabled.
  
Represents a menu, eg 1 = Walls, 2 = Electronics
+
If provided with a boolean, will change if its enabled.
  
----
+
If perfect circle brush is disabled, the circle brush will have single pixels sticking out on the sides.
  
''''number'' '''display'''''
+
<code>
 +
boolean tpt.perfectCircleBrush()
  
Represents a display mode, eg 4 = Fire, 6 = Heat
+
tpt.perfectCircleBrush(boolean enabled)
 +
</code>
  
----
+
==  Particles  ==
  
==  Lua API  ==
+
===  tpt.reset_spark  ===
'''The Powder Toy exposes the following methods to the Lua API:'''
 
===  Game  ===
 
====  tpt.set_pause  ====
 
Set the paused state of the game
 
======  tpt.set_pause(number state)  ======
 
====  tpt.set_console  ====
 
Set the visibility state of the console
 
======  tpt.set_console(number state)  ======
 
====  tpt.set_shortcuts  ====
 
Set whether keyboard shortcuts are enabled
 
======  tpt.set_shortcuts(number state)  ======
 
====  tpt.set_gravity  ====
 
Sets values on the gravity map, 3 overloads
 
======  tpt.set_gravity(number x, number y)  ======
 
======  tpt.set_gravity(number x, number y, number width, number height)  ======
 
======  tpt.set_gravity(number x, number y, number width, number height, number value)  ======
 
====  tpt.reset_gravity_field  ====
 
Resets regions on the gravity velocity map, 2 overloads
 
======  tpt.reset_gravity_field(number x, number y)  ======
 
======  tpt.reset_gravity_field(number x, number y, number width, number height)  ======
 
====  tpt.set_pressure  ====
 
Sets values on the pressure map, 3 overloads
 
======  tpt.set_pressure(number x, number y)  ======
 
======  tpt.set_pressure(number x, number y, number width, number height)  ======
 
======  tpt.set_pressure(number x, number y, number width, number height, number value)  ======
 
====  tpt.reset_velocity  ====
 
Resets regions on the velocity map, 2 overloads
 
======  tpt.reset_velocity(number x, number y)  ======
 
======  tpt.reset_velocity(number x, number y, number width, number height)  ======
 
====  tpt.hud  ====
 
Toggles HUD State
 
======  tpt.hud(number toggle)  ======
 
====  tpt.newtonian_gravity  ====
 
Toggles Newtonian Gravity State
 
======  tpt.newtonian_gravity(number toggle)  ======
 
====  tpt.ambient_heat  ====
 
Toggles Ambient Heat State
 
======  tpt.ambient_heat(number toggle)  ======
 
====  tpt.decorations_enable  ====
 
Toggles visibility of decorations
 
======  tpt.decorations_enable(number toggle)  ======
 
====  tpt.heat  ====
 
Toggles Heat Simulation State
 
======  tpt.heat(number toggle)  ======
 
====  tpt.active_menu  ====
 
Changes activated menu
 
======  tpt.active_menu(number menu)  ======
 
====  tpt.display_mode  ====
 
Changes activated display mode
 
======  tpt.display_mode(number display)  ======
 
====  tpt.setfpscap  ====
 
Changes the maximum FPS.
 
======  tpt.setfpscap(number fpscap)  ======
 
====  tpt.setfire  ====
 
Changes the strength of the games glowing effects. tpt.setfire(1) is default.
 
======  tpt.setfire(number strength)  ======
 
====  tpt.setwindowsize  ====
 
Changes the window settings. Scale is either 1 or 2. Returns a number, probably to indicate success.
 
======  tpt.setwindowsize(number scale, toggle fullscreen)  ======
 
===  Particles  ===
 
====  tpt.reset_spark  ====
 
 
Removes electrified wires from the simulation, resetting to the original material
 
Removes electrified wires from the simulation, resetting to the original material
======  tpt.reset_spark() ======
+
 
====  tpt.set_property  ====
+
<code>tpt.reset_spark()</code>
 +
 
 +
===  tpt.set_property  ===
 
Set various properties of particles for given criteria, 8 overloads
 
Set various properties of particles for given criteria, 8 overloads
======  tpt.set_property(string property, object value) ======
+
 
======  tpt.set_property(string property, object value, string type) ======
+
<code>
======  tpt.set_property(string property, object value, number index) ======
+
tpt.set_property(string property, object value)
======  tpt.set_property(string property, object value, number index, string type) ======
+
 
======  tpt.set_property(string property, object value, number x, number y) ======
+
tpt.set_property(string property, object value, string type)
======  tpt.set_property(string property, object value, number x, number y, string type) ======
+
 
======  tpt.set_property(string property, object value, number x, number y, number width, number height) ======
+
tpt.set_property(string property, object value, number index)
======  tpt.set_property(string property, object value, number x, number y, number width, number height, string type) ======
+
 
====  object tpt.get_property  ====
+
tpt.set_property(string property, object value, number index, string type)
Get various properties of a particle. Returns an ''object''
+
 
====== tpt.get_property(string property, number index) ======
+
tpt.set_property(string property, object value, number x, number y)
====== tpt.get_property(string property, number x, number y) ======
+
 
====  tpt.create  ====
+
tpt.set_property(string property, object value, number x, number y, string type)
 +
 
 +
tpt.set_property(string property, object value, number x, number y, number width, number height)
 +
 
 +
tpt.set_property(string property, object value, number x, number y, number width, number height, string type)
 +
</code>
 +
 
 +
=== tpt.set_wallmap ===
 +
Sets the wall at a position. Uses wall/air map coordinates. Divide the actual coordinate by 4 to get the wall coordinate. So to set the wall at (100, 200), pass 100/4 for x and 200/4 for y.
 +
 
 +
<code>
 +
tpt.set_wallmap(number x, number y, number walltype)
 +
 
 +
tpt.set_wallmap(number x, number y, number width, number height, number walltype)
 +
 
 +
tpt.set_wallmap(number x, number y, number width, number height, number fanVelocityX, number fanVelocityY, number walltype)
 +
</code>
 +
 
 +
=== tpt.get_wallmap ===
 +
Gets the wall at a position. Uses wall/air map coordinates. Divide the actual coordinate by 4 to get the wall coordinate. So to set the wall at (100, 200), pass 100/4 for x and 200/4 for y.
 +
 
 +
<code>
 +
tpt.get_wallmap(number x, number y)
 +
</code>
 +
 
 +
=== tpt.set_elecmap ===
 +
Sets the "electricity" flag for a wall at a position. This flag is usually set when walls are sparked. The value is decremented by 1 every frame, just like SPRK .life, and when it reaches 0 the wall is "unsparked". Uses wall/air map coordinates. Divide the actual coordinate by 4 to get the wall coordinate. So to set the wall at (100, 200), pass 100/4 for x and 200/4 for y.
 +
 
 +
<code>
 +
tpt.set_elecmap(number x, number y, number walltype)
 +
 
 +
tpt.set_elecmap(number x, number y, number width, number height, number walltype)
 +
</code>
 +
 
 +
=== tpt.get_elecmap ===
 +
Gets the "electricity" flag for a wall at a position. This flag is usually set when walls are sparked. Uses wall/air map coordinates. Divide the actual coordinate by 4 to get the wall coordinate. So to set the wall at (100, 200), pass 100/4 for x and 200/4 for y.
 +
 
 +
<code>
 +
tpt.get_elecmap(number x, number y)
 +
</code>
 +
 
 +
=== tpt.get_property  ===
 +
Returns various properties of a particle.
 +
 
 +
<code>
 +
tpt.get_property(string property, number index)
 +
 
 +
tpt.get_property(string property, number x, number y)
 +
</code>
 +
 
 +
===  tpt.create  ===
 
Create a particle at location.
 
Create a particle at location.
======  tpt.create(number x, number y, string type) ======
+
 
====  tpt.delete  ====
+
<code>tpt.create(number x, number y, string type)</code>
 +
 
 +
Returns the index of the newly created particle.
 +
 
 +
===  tpt.delete  ===
 
Delete a specific particle, or location.
 
Delete a specific particle, or location.
======  tpt.delete(number index) ======
+
 
======  tpt.delete(number x, number y) ======
+
<code>
====  tpt.start_getPartIndex  ====
+
tpt.delete(number index)
Start the iterator for receiving all indecies of the particles. (Used to help get particle indecies, see tpt.next_getPartIndex)
+
 
======  tpt.start_getPartIndex() ======
+
tpt.delete(number x, number y)
====  boolean tpt.next_getPartIndex  ====
+
</code>
 +
 
 +
===  tpt.start_getPartIndex  ===
 +
Start the iterator for receiving all indices of the particles. (Used to help get particle indices, see tpt.next_getPartIndex)
 +
 
 +
<code>tpt.start_getPartIndex()</code>
 +
 
 +
===  tpt.next_getPartIndex  ===
 
Jump to the next available particle index. Returns false if the iterator has reached the end of all particle indecies. Returns true if a new index was available. (Used to help get particle indecies, see tpt.getPartIndex)
 
Jump to the next available particle index. Returns false if the iterator has reached the end of all particle indecies. Returns true if a new index was available. (Used to help get particle indecies, see tpt.getPartIndex)
======  tpt.next_getPartIndex() ======
+
 
====  number tpt.getPartIndex  ====
+
<code>tpt.next_getPartIndex()</code>
 +
 
 +
===  tpt.getPartIndex  ===
 
Get the current index iterator.
 
Get the current index iterator.
======  tpt.getPartIndex() ======
+
 
====  number tpt.get_numOfParts  ====
+
<code>tpt.getPartIndex()</code>
 +
 
 +
index code example:
 +
<pre>
 +
    tpt.start_getPartIndex()
 +
    while tpt.next_getPartIndex() do
 +
        local index = tpt.getPartIndex()
 +
        if tpt.get_property("ctype",index) == 21 then
 +
          tpt.set_property("ctype","sing",index)
 +
        end
 +
    end
 +
</pre>
 +
 
 +
These functions are made obsolete by the function sim.parts(). That allows you to use Lua's iterators.
 +
 
 +
===  tpt.get_numOfParts  ===
 
Returns the number of particles currently on the screen.
 
Returns the number of particles currently on the screen.
======  tpt.get_numOfParts() ======
+
 
===  Drawing  ===
+
<code>tpt.get_numOfParts()</code>
====  number tpt.textwidth  ====
+
 
Measures (in pixels) the width of a given ''string''. Returns a ''number''
+
A newer way to get this is the variable sim.NUM_PARTS
======  tpt.textwidth(string text) ======
+
 
====  tpt.drawtext  ====
+
==  Drawing  ==
 +
 
 +
===  tpt.textwidth  ===
 +
Measures (in pixels) the width of a given string. Returns a number.
 +
 
 +
<code>tpt.textwidth(string text)</code>
 +
 
 +
===  tpt.drawtext  ===
 
Draw text to the screen (for one frame, only useful in scripts), 3 overloads
 
Draw text to the screen (for one frame, only useful in scripts), 3 overloads
======  tpt.drawtext(number x, number y, string text) ======
+
 
======  tpt.drawtext(number x, number y, string text, number red, number green, number blue) ======
+
<code>
======  tpt.drawtext(number x, number y, string text, number red, number green, number blue, number alpha) ======
+
tpt.drawtext(number x, number y, string text)
====  tpt.drawpixel  ====
+
 
 +
tpt.drawtext(number x, number y, string text, number red, number green, number blue)
 +
 
 +
tpt.drawtext(number x, number y, string text, number red, number green, number blue, number alpha)
 +
</code>
 +
 
 +
===  tpt.drawpixel  ===
 
Draws a pixel on the screen (for one frame, only useful in scripts), 3 overloads
 
Draws a pixel on the screen (for one frame, only useful in scripts), 3 overloads
======  tpt.drawpixel(number x, number y) ======
+
 
======  tpt.drawpixel(number x, number y, number red, number green, number blue) ======
+
<code>
======  tpt.drawpixel(number x, number y, number red, number green, number blue, number alpha) ======
+
tpt.drawpixel(number x, number y)
====  tpt.drawrect  ====
+
 
 +
tpt.drawpixel(number x, number y, number red, number green, number blue)
 +
 
 +
tpt.drawpixel(number x, number y, number red, number green, number blue, number alpha)
 +
 
 +
</code>
 +
 
 +
=== tpt.drawline  ===
 +
Draws a line on the screen (for one frame, only useful in scripts), 3 overloads.  The line starts at point (x1, y1) and ends at point (x2,y2).
 +
 
 +
<code>
 +
tpt.drawline(number x1, number y1, number x2, number y2)
 +
 
 +
tpt.drawline(number x1, number y1, number x2, number y2, number red, number green, number blue)
 +
 
 +
tpt.drawline(number x1, number y1, number x2, number y2, number red, number green, number blue, number alpha)
 +
 
 +
</code>
 +
 
 +
===  tpt.drawrect  ===
 
Draws a rectangle on the screen (for one frame, only useful in scripts), 3 overloads
 
Draws a rectangle on the screen (for one frame, only useful in scripts), 3 overloads
======  tpt.drawrect(number x, number y, number width, number height) ======
+
 
======  tpt.drawrect(number x, number y, number width, number height, number red, number green, number blue) ======
+
<code>
======  tpt.drawrect(number x, number y, number width, number height, number red, number green, number blue, number alpha) ======
+
tpt.drawrect(number x, number y, number width, number height)
====  tpt.fillrect  ====
+
 
 +
tpt.drawrect(number x, number y, number width, number height, number red, number green, number blue)
 +
 
 +
tpt.drawrect(number x, number y, number width, number height, number red, number green, number blue, number alpha)
 +
</code>
 +
 
 +
===  tpt.fillrect  ===
 
Draws a filled in rectangle on the screen (for one frame, only useful in scripts), 3 overloads
 
Draws a filled in rectangle on the screen (for one frame, only useful in scripts), 3 overloads
======  tpt.fillrect(number x, number y, number width, number height) ======
+
 
======  tpt.fillrect(number x, number y, number width, number height, number red, number green, number blue) ======
+
<code>
======  tpt.fillrect(number x, number y, number width, number height, number red, number green, number blue, number alpha) ======
+
tpt.fillrect(number x, number y, number width, number height)
===  Input/Output  ===
+
 
====  tpt.log  ====
+
tpt.fillrect(number x, number y, number width, number height, number red, number green, number blue)
 +
 
 +
tpt.fillrect(number x, number y, number width, number height, number red, number green, number blue, number alpha)
 +
</code>
 +
 
 +
Because tpt.fillrect is slightly broken in tpt, the coordinates will be off. It fills the rectangle from (x+1, y+1) to (x+w-1, y+h-1)
 +
 
 +
==  Input/Output  ==
 +
 
 +
===  tpt.log  ===
 
Log a message to the console
 
Log a message to the console
======  tpt.log(string text) ======
+
 
====  tpt.message_box  ====
+
<code>tpt.log(string text)</code>
 +
 
 +
===  tpt.message_box  ===
 
Display an OK-Only message box with a title and message.
 
Display an OK-Only message box with a title and message.
======  tpt.message_box(string title, string message) ======
+
 
====  string tpt.input  ====
+
<code>tpt.message_box(string title, string message)</code>
 +
 
 +
===  tpt.input  ===
 
Ask the user to input some text. Returns a string of what ever the user says. The argument "text" is pre-entered text (optional).
 
Ask the user to input some text. Returns a string of what ever the user says. The argument "text" is pre-entered text (optional).
======  tpt.input(string title, string message) ======
+
 
====== tpt.input(string title, string message, string text) ======
+
<code>
===  Events  ===
+
tpt.input(string title, string message)
====  tpt.register_step  ====
+
 
 +
tpt.input(string title, string message, string text)
 +
</code>
 +
 
 +
=== tpt.throw_error  ===
 +
Displays an error message box.
 +
 
 +
<code>tpt.throw_error(string text)</code>
 +
 
 +
=== tpt.confirm  ===
 +
Display an confirm message box with a title and message. Returns true if the button with button_name is clicked, returns false if Cancel is clicked.
 +
 
 +
<code>tpt.confirm(string title, string message,string button_name)</code>
 +
 
 +
==  Events  ==
 +
 
 +
The old event api was removed in 94.0, and is only still present through a compatibility script. Please use the new api instead: [[Lua_API:Event|Event]]
 +
 
 +
===  tpt.register_step  ===
 +
'''This function is DEPRECATED in TPT 94.0 and is only provided via a compatibility script'''
 +
 
 
Register a function to be run on every frame
 
Register a function to be run on every frame
======  tpt.register_step(function func) ======
+
 
====  tpt.unregister_step  ====
+
<code>tpt.register_step(function func)</code>
 +
 
 +
===  tpt.unregister_step  ===
 +
'''This function is DEPRECATED in TPT 94.0 and is only provided via a compatibility script'''
 +
 
 
Unregister a previously registered function
 
Unregister a previously registered function
======  tpt.unregister_step(function func) ======
+
 
====  tpt.register_mouseclick  ====
+
<code>tpt.unregister_step(function func)</code>
Register a function to be run every time the mouse clicks\\ \\
+
 
Passes: (''number mousex, number mousey, number button, number event'')
+
===  tpt.register_mouseclick  ===
======  tpt.register_mouseclick(function func) ======
+
'''This function is DEPRECATED in TPT 94.0 and is only provided via a compatibility script'''
====  tpt.unregister_mouseclick  ====
+
 
 +
Register a function to be run every time the mouse clicks.
 +
 
 +
Your function will also be called when the mouse is released or held, or when the mouse wheel is used. Event equals 1 when the mouse gets pressed, 2 when the mouse gets released, and 3 if it is held. If your function returns false, mouse events in the normal Powder Toy will be ignored.
 +
 
 +
Function arguments: mousex, mousey, button, event
 +
 
 +
<code>tpt.register_mouseclick(function func)</code>
 +
 
 +
===  tpt.unregister_mouseclick  ===
 +
'''This function is DEPRECATED in TPT 94.0 and is only provided via a compatibility script'''
 +
 
 
Unregister a previously registered function
 
Unregister a previously registered function
======  tpt.unregister_mouseclick(function func) ======
+
 
====  tpt.register_keypress  ====
+
<code>tpt.unregister_mouseclick(function func)</code>
Register a function to be run every time a key is pressed\\ \\
+
 
Passes: (''string key, number key, number modifier'')
+
===  tpt.register_keypress  ===
======  tpt.register_keypress(function func) ======
+
'''This function is DEPRECATED in TPT 94.0 and is only provided via a compatibility script'''
====  tpt.unregister_keypress  ====
+
 
 +
Register a function to be run every time a key is pressed.
 +
 
 +
Your function will also be called when a key is released. Event equals 1 when a key is pressed, and 2 when it gets released. If your function returns false, key presses in the normal Powder Toy will be ignored.
 +
 
 +
Function arguments: key, nkey, modifier, event
 +
 
 +
<code>tpt.register_keypress(function func)</code>
 +
 
 +
===  tpt.unregister_keypress  ===
 +
'''This function is DEPRECATED in TPT 94.0 and is only provided via a compatibility script'''
 +
 
 
Unregister a previously registered function
 
Unregister a previously registered function
======  tpt.unregister_keypress(function func)  ======
 
===  Misc  ===
 
====  string tpt.get_name  ====
 
Get the current username, returns a ''string''
 
======  tpt.get_name()  ======
 
====  tpt.throw_error  ====
 
Displays an error message
 
======  tpt.throw_error(string text)  ======
 
====  tpt.setdebug  ====
 
Sets the "debug mode". Only odd numbers seem to do anything for now.
 
======  tpt.setdebug(number mode)  ======
 
==  Mod's with Lua Functions  ==
 
====  Me4502's Mod  ====
 
=====  NOTICE: THESE FUNCTIONS ARE AVAILABLE IN VERSION 3.0b11 OR LATER  =====
 
=====  String Property Additions  =====
 
"collision"
 
"airdrag"
 
"flammable"
 
"weight"
 
"falldown"
 
"gravity"
 
"explosive"
 
"meltable"
 
"hardness"
 
"name"
 
"airloss"
 
"loss"
 
"hotair"
 
"actas"
 
  
=====  New Functions =====
+
<code>tpt.unregister_keypress(function func)</code>
====== tpt.throw_error("") ======
+
 
====== tpt.getscript(""======
+
==  Misc  ==
For the following, 1 in the ()'s is on 0 is off
+
 
====== tpt.hud() ======
+
===  tpt.get_name ===
====== tpt.newtonian_gravity() ======
+
Returns the current username.
====== tpt.ambient_heat() ======
+
 
====== tpt.decorations_enable()  ======
+
<code>tpt.get_name()</code>
====== tpt.heat() ======
+
 
For the following the number of the value you want goes into the ()'s
+
=== tpt.setdebug  ===
======  tpt.active_menu()  ======
+
Sets the "debug mode". It works using bitmasks, so you can turn on multiple debug features at the same time.<br/>
====== tpt.display_mode()  ======
+
Setting 0x1 will display info on the number of particles on the screen.<br/>
======  tpt.set_glow() ======
+
Setting 0x2 will draw a graph showing the percentages of each type of element on the screen.<br/>
==  Simple Example Code  ==
+
Setting 0x4 will display useful information when you draw lines using shift.<br/>
-- This line is a comment. Anything written after the -- is considered a Comment and will not be read by Lua.
+
Setting 0x8 enables subframe particle debugging. Use alt+f to step one particle at a time. Use shift+f to step up to the particle underneath the mouse. When not over a particle, it advances to the end of the frame.
+
 
-- Set the console's state to 0. This will hide the console.
+
<code>tpt.setdebug(number mode)</code>
tpt.set_console(0)
+
 
+
=== tpt.element  ===
-- Here we define our main function for the script
+
Returns an element's number. For example, it would return 28 for dmnd. If passed a number it will return the name instead.
function ClassicPowder()
+
 
local ox = 125 -- This will be our offset for the different elements we will create.
+
<code>tpt.element(string elementname)
local y = 4 -- where on the y (vertical) axis where we will create our elements.
+
 
+
tpt.element(number elementid)</code>
local x = ox -- where on the x (horizontal) axis where we will create our elements. we will start the x value with what ever ox is above.
+
 
for i=0, 10 do -- this is a for loop. everything between the do and end will loop until i hits 10. i increases by 1 every loop.
+
=== tpt.element_func  ===
tpt.create(x + i, y, "DUST") --create a dust particle
+
'''This function is DEPRECATED in TPT 97.0 and is only provided via a compatibility script'''
end
+
<br/>
+
Use [https://powdertoy.co.uk/Wiki/W/Lua_API:Elements.html#elements.property elements.property] with "Update" instead.
x = x + ox -- increase the x axis value by the offset x (ox) value above.
+
 
for i=0, 10 do
+
=== tpt.graphics_func  ===
tpt.create(x + i, y, "WATR") --create a water particle
+
'''This function is DEPRECATED in TPT 97.0 and is only provided via a compatibility script'''
end
+
<br/>
+
Use [https://powdertoy.co.uk/Wiki/W/Lua_API:Elements.html#elements.property elements.property] with "Graphics" instead.
x = x + ox
+
 
for i=0, 10 do
+
=== tpt.screenshot ===
tpt.create(x + i, y, "SALT")
+
Takes a screenshot of the current screen, minus the menu and HUD.
end
+
 
+
<code>tpt.screenshot()
x = x + ox
+
 
for i=0, 10 do
+
tpt.screenshot(boolean fullscreen,number screenshot format)</code>
tpt.create(x + i, y, "OIL")
+
 
end
+
'''Screenshot format''':
+
 
return false
+
0 - png
end
+
 
+
1 - bmp
-- Register the step function ClassicPowder. This will make the ClassicPowder function run every tick of Powder Toy.
+
 
tpt.register_step(ClassicPowder)
+
2 - ppm
 +
 
 +
'''Examples''':
 +
 
 +
tpt.screenshot(1,1) - take fullscreen screenshot in bmp format
 +
 
 +
tpt.screenshot(1,2) - take fullscreen screenshot in ppm format
 +
 
 +
=== tpt.get_clipboard ===
 +
Returns contents of the clipboard.
 +
 
 +
<code>tpt.get_clipboard()</code>
 +
 
 +
=== tpt.set_clipboard ===
 +
Copy to clipboard.
 +
 
 +
<code>tpt.set_clipboard(string text)</code>
 +
 
 +
=== tpt.record ===
 +
Records each drawn frame and saves them all in a unique folder inside a folder called "recordings" in the .ppm format.
 +
 
 +
Returns the name of the folder inside the "recordings" folder.
 +
 
 +
The record argument if true will start recording and if false will stop recording.
 +
 
 +
<code>
 +
number tpt.record(boolean record)
 +
</code>
 +
 
 +
=== tpt.getscript ===
 +
'''This function is DEPRECATED in TPT 98.0 and can only be used to install script manager'''
 +
 
 +
This function rejects all input, unless the arguments are those commonly used to install script manager. It is kept only so that old installation instructions still work. Please use tpt.installScriptManager instead.
 +
 
 +
<code>
 +
tpt.getscript(1, "autorun.lua", 1)
 +
</code>
 +
 
 +
=== tpt.installScriptManager ===
 +
Downloads [https://powdertoy.co.uk/Discussions/Thread/View.html?Thread=19400 script manager] and installs it to TPT's shared data folder as autorun.lua. It will be immediately run, and run on all subsequent launches too.
 +
 
 +
<code>
 +
tpt.installScriptManager()
 +
</code>
 +
 
 +
= Constants =
 +
 
 +
All of these constants can be accessed by tpt.<constant name>.
 +
 
 +
=== tpt.selectedl ===
 +
Current element / tool on mouse1
 +
 
 +
=== tpt.selectedr ===
 +
Current element / tool on mouse2
 +
 
 +
=== tpt.selecteda ===
 +
Current element / tool on mouse3 (middle click)
 +
 
 +
=== tpt.selectedreplace ===
 +
Current element to be used in replace mode (green outline)
 +
 
 +
=== tpt.brushx ===
 +
Current brush width
 +
 
 +
=== tpt.brushy ===
 +
Current brush height
 +
 
 +
=== tpt.brushID ===
 +
Current brush ID, 0 = circle, 1 = square, 2 = triangle, higher = custom brushes
 +
 
 +
Note that these constants are not read-only so if you run
 +
<pre>tpt.selectedl = "DEFAULT_PT_SPRK"</pre>
 +
it will change the element on mouse1 to sprk
 +
 
 +
= Actual constants =
 +
 
 +
* <code>tpt.version</code>: Table which contains version-related constants
 +
** <code>tpt.version.major</code>: Major version number. May not match vanilla in mods.
 +
** <code>tpt.version.minor</code>: Minor version number. May not match vanilla in mods.
 +
** <code>tpt.version.build</code>: Build number. May not match vanilla in mods.
 +
** <code>tpt.version.upstreamMajor</code>: Upstream (vanilla) major version number
 +
** <code>tpt.version.upstreamMinor</code>: Upstream (vanilla) minor version number
 +
** <code>tpt.version.upstreamBuild</code>: Upstream (vanilla) build number
 +
** <code>tpt.version.modid</code>: Mod id, 0 for vanilla TPT
 +
** <code>tpt.snapshot</code>: boolean flag, true if this is a snapshot
 +
** <code>tpt.version.beta</code>: boolean flag, true if this is a beta
 +
** <code>tpt.version.vcstag</code>: git sha256 hash. May be nil in some builds.
 +
 
 +
* <code>tpt.DEBUG_PARTS</code>: Turn on parts/pmap free spot graph
 +
* <code>tpt.DEBUG_ELEMENTPOP</code>: Turn on element population graph
 +
* <code>tpt.DEBUG_LINES</code>: Turn on debug lines when using line tool
 +
* <code>tpt.DEBUG_PARTICLE</code>: Turn on subframe debugging and enable shortcuts
 +
* <code>tpt.DEBUG_SURFNORM</code>: Turn on PHOT surface normal graphics during reflection / refraction
 +
 
 +
=  Simple Example Code  =
 +
<pre>
 +
  -- This line is a comment. Anything written after the -- is considered a Comment and will not be read by Lua.
 +
  -- Comment can be multiline, for this you should write it in --[[ and ]]--
 +
  -- Set the console's state to 0. This will hide the console.
 +
  tpt.set_console(0)
 +
 
 +
  -- Here we define our main function for the script
 +
  local function ClassicPowder()
 +
    local ox = 125 -- This will be our offset for the different elements we will create.
 +
    local y = 4 -- where on the y (vertical) axis where we will create our elements.
 +
 
 +
    local x = ox -- where on the x (horizontal) axis where we will create our elements. we will start the x value with what ever ox is above.
 +
    for i=0, 10 do -- this is a for loop. everything between the do and end will loop until i hits 10. i increases by 1 every loop.
 +
        tpt.create(x + i, y, "STNE") --create a dust particle
 +
    end
 +
 
 +
    x = x + ox -- increase the x axis value by the offset x (ox) value above
 +
    for i=0, 10 do
 +
        tpt.create(x + i, y, "WATR") --create a water particle
 +
    end
 +
 
 +
    x = x + ox
 +
    for i=0, 10 do
 +
        tpt.create(x + i, y, "SALT")
 +
    end
 +
 
 +
    x = x + ox
 +
    for i=0, 10 do
 +
        tpt.create(x + i, y, "OIL")
 +
    end
 +
 
 +
    return false
 +
  end
 +
 
 +
  -- Register the step function ClassicPowder. This will make the ClassicPowder function run every tick of Powder Toy.
 +
  tpt.register_step(ClassicPowder)
 +
</pre>
 +
[[Category:Lua]]

Latest revision as of 21:01, 10 March 2024

Language: English  • Deutsch

This page describes an old version of TPT's Lua API, most of which is unsuitable for new scripts. For the new API, see Powder Toy Lua API.

You may open the Lua Console by hitting the [`] key. (Also known as the tilde [~] key, or the [¬] key) click here to view key


You may be used to this style of console commands: !set type dust metl. This can be useful, but Lua is an entire programming language that can do much more powerful things. The equivalent command in TPT's Lua is tpt.set_property("type", "metl", "dust") (see Lua#tpt.set_property )

This page describes the TPT Lua API, not the Lua language itself. But, you may research Lua on your own. If you're a beginner, look at this: http://www.lua.org/pil/ . If more advanced, a list of all the functions is here: http://www.lua.org/manual/5.1/

Also, FeynmanTechnologies has written a tutorial on some of the most basic Lua features here: https://powdertoy.co.uk/Discussions/Thread/View.html?Thread=17801

The Lua Console provides the ability to create scripts using Lua, a very simple scripting language. With the ability to script with Lua, users are now able to create simple modifications to the game without editing source code. For information on how to run scripts, see Running Lua Scripts

Contents

Lua API

The Powder Toy exposes the following methods to the Lua API:

Game

tpt.set_pause

tpt.set_pause(number state)

Sets the paused state of the game.

The number argument is either 0 or 1, where 1 means the game will be paused, and 0 will unpause the game. If you don't pass in any arguments, the command will return an integer, either 0 or 1, about whether the game is currently paused.

Examples:

Pause the game: tpt.set_pause(1)

Get if the game is paused currently: tpt.set_pause() == 1

tpt.set_console

tpt.set_console(number state)

Set the visibility state of the console.

The number argument can be either 0 or 1, where 1 means the console will be opened, and 0 will close the console. If you don't pass in any arguments, the command will return an integer, either 0 or 1, about whether the console is currently opened.

Examples:

Open the console: tpt.set_console(1)

Get if the console is currently open: tpt.set_console() == 1

tpt.set_shortcuts

This function is REMOVED in TPT 94.0

tpt.set_shortcuts(number state)

Set whether one can use keyboard shortcuts such as making a stamp or opening the console or changing view modes.

The number argument can be either 0 or 1, where 1 means keys will be enabled, and 0 will disable key shortcuts. If you don't pass in any arguments, the command will return an integer, either 0 or 1, about whether key shortcuts are enabled right now.

When you want to make a key command which uses some other key, don't use this, rather disable default behavior for that one key only by returning false from inside your callback.

Examples:

Disable keyboard shortcuts: tpt.set_shortcuts(0)

Get if keyboard shortcuts are currently disabled: tpt.set_shortcuts(-1) == 1

tpt.set_gravity

tpt.set_gravity(number x, number y, number width, number height, number value)

Sets Newtonian Gravity at a position or area to some value.

Default values:

x = 0
y = 0
width = XRES/CELL = 612 / 4 = 153
height = YRES/CELL = 384 / 4 = 96
value = 0

Examples:

Reset gravity in the cell at point (150, 150): tpt.set_gravity(150 / sim.CELL, 150 / sim.CELL)

Reset gravity from (100,100) to (300,300): tpt.set_gravity(100 / sim.CELL, 100 / sim.CELL, 200 / sim.CELL, 200 / sim.CELL)

Set the entire stage's gravity to 1000: tpt.set_gravity(nil, nil, nil, nil, 1000)

tpt.reset_gravity_field

tpt.reset_gravity_field(number x, number y, number width, number height)

Thoroughly resets Newtonian gravity on a given point.

Instead of tpt.set_gravity which only modifies sim->gravmap, this code modifies sim->gravp,sim->gravx and sim->gravy. Mmm, gravy.

Default values:

x = 0
y = 0
width = XRES/CELL = 612 / 4 = 153
height = YRES/CELL = 384 / 4 = 96

Examples:

Thoroughly reset gravity in the cell at point (150, 150): tpt.reset_gravity_field(150 / sim.CELL, 150 / sim.CELL)

Reset gravity from (100, 100) to (300,300): tpt.reset_gravity_field(100 / sim.CELL, 100 / sim.CELL, 200 / sim.CELL, 200 / sim.CELL)

tpt.set_pressure

tpt.set_pressure(number x, number y, number width, number height, number value)

Sets or resets pressure in the pressure map to some pressure. I sometimes imagine how much I can repeat the word "pressure" inside a sentence before it becomes gibberish.

Default values:

x = 0
y = 0
width = XRES/CELL = 612 / 4 = 153
height = YRES/CELL = 384 / 4 = 96
value = 0

Examples:

Reset pressure everywhere: tpt.set_pressure()

Set pressure of cell at (100, 100) to 200: tpt.set_pressure(100 / sim.CELL, 100 / sim.CELL, 1, 1, 200)

Set pressure everywhere to 200: tpt.set_pressure(nil,nil,nil,nil,200)

tpt.reset_velocity

tpt.reset_velocity(number x, number y, number width, number height)

Sets velocity (both x and y) in a given region or point to 0.

Default values:

x = 0
y = 0
width = XRES/CELL = 612 / 4 = 153
height = YRES/CELL = 384 / 4 = 96

Examples:

Reset velocity everywhere: tpt.reset_velocity()

Reset velocity in the cell at point (100,100): tpt.reset_velocity(100 / sim.CELL, 100 / sim.CELL, 1, 1)

tpt.hud

tpt.hud(number state)

Set HUD visibility.

Does the same thing as pressing the H key normally. The number argument can be either 0 or 1, where 1 will show the HUD, and 0 will hide the HUD. If you don't pass in any arguments, the command will return an integer, either 0 or 1, about whether the HUD is visible right now.

tpt.newtonian_gravity

tpt.newtonian_gravity(number state)

Sets Newtonian Gravity on and off.

Does the same thing as Ctrl+N in normal gameplay.

The number argument can be either 0 or 1, where 1 will enable Newtonian Gravity, and 0 will disable Newtonian Gravity. If you don't pass in any arguments, the command will return an integer, either 0 or 1, about whether Newtonian Gravity is turned on at the given moment.

tpt.ambient_heat

tpt.ambient_heat(number state)

Toggles Ambient Heat state.

The number argument can be either 0 or 1, where 1 will enable Ambient Heat, 0 will disable it. If you don't pass in any arguments, the command will return an integer, either 0 or 1, about whether Ambient Heat is turned on at the given moment.

tpt.decorations_enable

tpt.decorations_enable(number state)

Toggle drawing decorations.

The number argument can be either 0 or 1, where 1 will enable decorations, and 0 will disable them. If you don't pass in any arguments, the command will return an integer, either 0 or 1, about whether decorations are turned on at the given moment.

tpt.heat

tpt.heat(number state)

Toggles Heat Simulation.

The number argument can be either 0 or 1, where 1 will enable heat, and 0 will disable it. If you don't pass in any arguments, the command will return an integer, either 0 or 1, about whether heat is turned on at the given moment.

It's usually wise not to disable this, as there are practically no saves left that need the compatibility mode in order to work. Nevertheless this option exists.

tpt.active_menu

tpt.active_menu(number menu)

Changes activated menu. If you don't pass in any arguments, the command will return the currently active menu.

The menu IDs are detailed here: Element_Properties#Menu_sections

Example: tpt.active_menu(elem.SC_EXPLOSIVE)

tpt.menu_enabled

boolean tpt.menu_enabled(number menuID)

tpt.menu_enabled(number menuID, boolean enabled)

Returns true if a menu section is enabled.

If provided a boolean, will set if a menu section is enabled.

tpt.num_menus

number tpt.num_menus()

number tpt.num_menus(boolean onlyEnabled)

Returns the number of menus.

The optional onlyEnabled boolean is true by default.

tpt.display_mode

tpt.display_mode(number display)

Changes activated display mode.

There's 11 display modes, detailed here [[1]]
Note that the order of display modes is shifted by 1 making velocity mode first and alternative velocity last.

Display Modes

0 = Velocity
1 = Pressure
2 = Persistent
3 = Fire
4 = Blob
5 = Heat
6 = Fancy
7 = Nothing
8 = Heat Gradient
9 = Life Gradient
10 = Alternate Velocity

tpt.setfpscap

tpt.setfpscap(number fpscap)

Changes the upper FPS limit the program will run at. This value is 60 by default.

Don't set it too high, it'll eat all your CPU speed and make the game too responsive! Don't also set it too low, since UI and everything related to it uses the same FPS, so you'll find buttons and stuff not working.

If you don't pass in any arguments, it will return the current fps cap. If you set the fpscap to 2, this will uncap the framerate.

tpt.setdrawcap

Changes the rate that particle graphics and the UI render to the screen. This is separate from the fpscap, which only affects the simulation. The drawcap allows TPT to skip drawing every frame. This may increase the framerate in some instances.

The default is set to the maximum refresh rate of all attached monitors.

tpt.setfire

Changes the strength of the game's glowing effects. tpt.setfire(1) is default.

tpt.setfire(number strength)

tpt.setwindowsize

tpt.setwindowsize(number scale, number fullscreen)

Changes a few special properties as to what size the game renders at.

Scale is a multiplier by which every pixel shall get multiplied at, currently it can either be 1 (612x384) or 2 (1224x768).

Full screen is a toggle (0 or 1) that enables "kiosk mode", which basically scales the game up to fill the screen and makes the rest of the edge black.

tpt.toggle_pause

Toggle pause.

tpt.toggle_pause()

tpt.watertest

REPLACED by simulation.waterEqualisation

Toggles water equalization. Returns current state.

number tpt.watertest()

tpt.perfectCircleBrush

Returns true if perfect circle brush is enabled.

If provided with a boolean, will change if its enabled.

If perfect circle brush is disabled, the circle brush will have single pixels sticking out on the sides.

boolean tpt.perfectCircleBrush()

tpt.perfectCircleBrush(boolean enabled)

Particles

tpt.reset_spark

Removes electrified wires from the simulation, resetting to the original material

tpt.reset_spark()

tpt.set_property

Set various properties of particles for given criteria, 8 overloads

tpt.set_property(string property, object value)

tpt.set_property(string property, object value, string type)

tpt.set_property(string property, object value, number index)

tpt.set_property(string property, object value, number index, string type)

tpt.set_property(string property, object value, number x, number y)

tpt.set_property(string property, object value, number x, number y, string type)

tpt.set_property(string property, object value, number x, number y, number width, number height)

tpt.set_property(string property, object value, number x, number y, number width, number height, string type)

tpt.set_wallmap

Sets the wall at a position. Uses wall/air map coordinates. Divide the actual coordinate by 4 to get the wall coordinate. So to set the wall at (100, 200), pass 100/4 for x and 200/4 for y.

tpt.set_wallmap(number x, number y, number walltype)

tpt.set_wallmap(number x, number y, number width, number height, number walltype)

tpt.set_wallmap(number x, number y, number width, number height, number fanVelocityX, number fanVelocityY, number walltype)

tpt.get_wallmap

Gets the wall at a position. Uses wall/air map coordinates. Divide the actual coordinate by 4 to get the wall coordinate. So to set the wall at (100, 200), pass 100/4 for x and 200/4 for y.

tpt.get_wallmap(number x, number y)

tpt.set_elecmap

Sets the "electricity" flag for a wall at a position. This flag is usually set when walls are sparked. The value is decremented by 1 every frame, just like SPRK .life, and when it reaches 0 the wall is "unsparked". Uses wall/air map coordinates. Divide the actual coordinate by 4 to get the wall coordinate. So to set the wall at (100, 200), pass 100/4 for x and 200/4 for y.

tpt.set_elecmap(number x, number y, number walltype)

tpt.set_elecmap(number x, number y, number width, number height, number walltype)

tpt.get_elecmap

Gets the "electricity" flag for a wall at a position. This flag is usually set when walls are sparked. Uses wall/air map coordinates. Divide the actual coordinate by 4 to get the wall coordinate. So to set the wall at (100, 200), pass 100/4 for x and 200/4 for y.

tpt.get_elecmap(number x, number y)

tpt.get_property

Returns various properties of a particle.

tpt.get_property(string property, number index)

tpt.get_property(string property, number x, number y)

tpt.create

Create a particle at location.

tpt.create(number x, number y, string type)

Returns the index of the newly created particle.

tpt.delete

Delete a specific particle, or location.

tpt.delete(number index)

tpt.delete(number x, number y)

tpt.start_getPartIndex

Start the iterator for receiving all indices of the particles. (Used to help get particle indices, see tpt.next_getPartIndex)

tpt.start_getPartIndex()

tpt.next_getPartIndex

Jump to the next available particle index. Returns false if the iterator has reached the end of all particle indecies. Returns true if a new index was available. (Used to help get particle indecies, see tpt.getPartIndex)

tpt.next_getPartIndex()

tpt.getPartIndex

Get the current index iterator.

tpt.getPartIndex()

index code example:

     tpt.start_getPartIndex()
     while tpt.next_getPartIndex() do
        local index = tpt.getPartIndex()
        if tpt.get_property("ctype",index) == 21 then
           tpt.set_property("ctype","sing",index)
        end
     end

These functions are made obsolete by the function sim.parts(). That allows you to use Lua's iterators.

tpt.get_numOfParts

Returns the number of particles currently on the screen.

tpt.get_numOfParts()

A newer way to get this is the variable sim.NUM_PARTS

Drawing

tpt.textwidth

Measures (in pixels) the width of a given string. Returns a number.

tpt.textwidth(string text)

tpt.drawtext

Draw text to the screen (for one frame, only useful in scripts), 3 overloads

tpt.drawtext(number x, number y, string text)

tpt.drawtext(number x, number y, string text, number red, number green, number blue)

tpt.drawtext(number x, number y, string text, number red, number green, number blue, number alpha)

tpt.drawpixel

Draws a pixel on the screen (for one frame, only useful in scripts), 3 overloads

tpt.drawpixel(number x, number y)

tpt.drawpixel(number x, number y, number red, number green, number blue)

tpt.drawpixel(number x, number y, number red, number green, number blue, number alpha)

tpt.drawline

Draws a line on the screen (for one frame, only useful in scripts), 3 overloads. The line starts at point (x1, y1) and ends at point (x2,y2).

tpt.drawline(number x1, number y1, number x2, number y2)

tpt.drawline(number x1, number y1, number x2, number y2, number red, number green, number blue)

tpt.drawline(number x1, number y1, number x2, number y2, number red, number green, number blue, number alpha)

tpt.drawrect

Draws a rectangle on the screen (for one frame, only useful in scripts), 3 overloads

tpt.drawrect(number x, number y, number width, number height)

tpt.drawrect(number x, number y, number width, number height, number red, number green, number blue)

tpt.drawrect(number x, number y, number width, number height, number red, number green, number blue, number alpha)

tpt.fillrect

Draws a filled in rectangle on the screen (for one frame, only useful in scripts), 3 overloads

tpt.fillrect(number x, number y, number width, number height)

tpt.fillrect(number x, number y, number width, number height, number red, number green, number blue)

tpt.fillrect(number x, number y, number width, number height, number red, number green, number blue, number alpha)

Because tpt.fillrect is slightly broken in tpt, the coordinates will be off. It fills the rectangle from (x+1, y+1) to (x+w-1, y+h-1)

Input/Output

tpt.log

Log a message to the console

tpt.log(string text)

tpt.message_box

Display an OK-Only message box with a title and message.

tpt.message_box(string title, string message)

tpt.input

Ask the user to input some text. Returns a string of what ever the user says. The argument "text" is pre-entered text (optional).

tpt.input(string title, string message)

tpt.input(string title, string message, string text)

tpt.throw_error

Displays an error message box.

tpt.throw_error(string text)

tpt.confirm

Display an confirm message box with a title and message. Returns true if the button with button_name is clicked, returns false if Cancel is clicked.

tpt.confirm(string title, string message,string button_name)

Events

The old event api was removed in 94.0, and is only still present through a compatibility script. Please use the new api instead: Event

tpt.register_step

This function is DEPRECATED in TPT 94.0 and is only provided via a compatibility script

Register a function to be run on every frame

tpt.register_step(function func)

tpt.unregister_step

This function is DEPRECATED in TPT 94.0 and is only provided via a compatibility script

Unregister a previously registered function

tpt.unregister_step(function func)

tpt.register_mouseclick

This function is DEPRECATED in TPT 94.0 and is only provided via a compatibility script

Register a function to be run every time the mouse clicks.

Your function will also be called when the mouse is released or held, or when the mouse wheel is used. Event equals 1 when the mouse gets pressed, 2 when the mouse gets released, and 3 if it is held. If your function returns false, mouse events in the normal Powder Toy will be ignored.

Function arguments: mousex, mousey, button, event

tpt.register_mouseclick(function func)

tpt.unregister_mouseclick

This function is DEPRECATED in TPT 94.0 and is only provided via a compatibility script

Unregister a previously registered function

tpt.unregister_mouseclick(function func)

tpt.register_keypress

This function is DEPRECATED in TPT 94.0 and is only provided via a compatibility script

Register a function to be run every time a key is pressed.

Your function will also be called when a key is released. Event equals 1 when a key is pressed, and 2 when it gets released. If your function returns false, key presses in the normal Powder Toy will be ignored.

Function arguments: key, nkey, modifier, event

tpt.register_keypress(function func)

tpt.unregister_keypress

This function is DEPRECATED in TPT 94.0 and is only provided via a compatibility script

Unregister a previously registered function

tpt.unregister_keypress(function func)

Misc

tpt.get_name

Returns the current username.

tpt.get_name()

tpt.setdebug

Sets the "debug mode". It works using bitmasks, so you can turn on multiple debug features at the same time.
Setting 0x1 will display info on the number of particles on the screen.
Setting 0x2 will draw a graph showing the percentages of each type of element on the screen.
Setting 0x4 will display useful information when you draw lines using shift.
Setting 0x8 enables subframe particle debugging. Use alt+f to step one particle at a time. Use shift+f to step up to the particle underneath the mouse. When not over a particle, it advances to the end of the frame.

tpt.setdebug(number mode)

tpt.element

Returns an element's number. For example, it would return 28 for dmnd. If passed a number it will return the name instead.

tpt.element(string elementname)

tpt.element(number elementid)

tpt.element_func

This function is DEPRECATED in TPT 97.0 and is only provided via a compatibility script
Use elements.property with "Update" instead.

tpt.graphics_func

This function is DEPRECATED in TPT 97.0 and is only provided via a compatibility script
Use elements.property with "Graphics" instead.

tpt.screenshot

Takes a screenshot of the current screen, minus the menu and HUD.

tpt.screenshot()

tpt.screenshot(boolean fullscreen,number screenshot format)

Screenshot format:

0 - png

1 - bmp

2 - ppm

Examples:

tpt.screenshot(1,1) - take fullscreen screenshot in bmp format

tpt.screenshot(1,2) - take fullscreen screenshot in ppm format

tpt.get_clipboard

Returns contents of the clipboard.

tpt.get_clipboard()

tpt.set_clipboard

Copy to clipboard.

tpt.set_clipboard(string text)

tpt.record

Records each drawn frame and saves them all in a unique folder inside a folder called "recordings" in the .ppm format.

Returns the name of the folder inside the "recordings" folder.

The record argument if true will start recording and if false will stop recording.

number tpt.record(boolean record)

tpt.getscript

This function is DEPRECATED in TPT 98.0 and can only be used to install script manager

This function rejects all input, unless the arguments are those commonly used to install script manager. It is kept only so that old installation instructions still work. Please use tpt.installScriptManager instead.

tpt.getscript(1, "autorun.lua", 1)

tpt.installScriptManager

Downloads script manager and installs it to TPT's shared data folder as autorun.lua. It will be immediately run, and run on all subsequent launches too.

tpt.installScriptManager()

Constants

All of these constants can be accessed by tpt.<constant name>.

tpt.selectedl

Current element / tool on mouse1

tpt.selectedr

Current element / tool on mouse2

tpt.selecteda

Current element / tool on mouse3 (middle click)

tpt.selectedreplace

Current element to be used in replace mode (green outline)

tpt.brushx

Current brush width

tpt.brushy

Current brush height

tpt.brushID

Current brush ID, 0 = circle, 1 = square, 2 = triangle, higher = custom brushes

Note that these constants are not read-only so if you run

tpt.selectedl = "DEFAULT_PT_SPRK"

it will change the element on mouse1 to sprk

Actual constants

  • tpt.version: Table which contains version-related constants
    • tpt.version.major: Major version number. May not match vanilla in mods.
    • tpt.version.minor: Minor version number. May not match vanilla in mods.
    • tpt.version.build: Build number. May not match vanilla in mods.
    • tpt.version.upstreamMajor: Upstream (vanilla) major version number
    • tpt.version.upstreamMinor: Upstream (vanilla) minor version number
    • tpt.version.upstreamBuild: Upstream (vanilla) build number
    • tpt.version.modid: Mod id, 0 for vanilla TPT
    • tpt.snapshot: boolean flag, true if this is a snapshot
    • tpt.version.beta: boolean flag, true if this is a beta
    • tpt.version.vcstag: git sha256 hash. May be nil in some builds.
  • tpt.DEBUG_PARTS: Turn on parts/pmap free spot graph
  • tpt.DEBUG_ELEMENTPOP: Turn on element population graph
  • tpt.DEBUG_LINES: Turn on debug lines when using line tool
  • tpt.DEBUG_PARTICLE: Turn on subframe debugging and enable shortcuts
  • tpt.DEBUG_SURFNORM: Turn on PHOT surface normal graphics during reflection / refraction

Simple Example Code

  -- This line is a comment. Anything written after the -- is considered a Comment and will not be read by Lua.
  -- Comment can be multiline, for this you should write it in --[[ and ]]--
  -- Set the console's state to 0. This will hide the console.
  tpt.set_console(0)
  
  -- Here we define our main function for the script
  local function ClassicPowder()
     local ox = 125 -- This will be our offset for the different elements we will create.
     local y = 4 -- where on the y (vertical) axis where we will create our elements.
  
     local x = ox -- where on the x (horizontal) axis where we will create our elements. we will start the x value with what ever ox is above.
     for i=0, 10 do -- this is a for loop. everything between the do and end will loop until i hits 10. i increases by 1 every loop.
        tpt.create(x + i, y, "STNE") --create a dust particle
     end
  
     x = x + ox -- increase the x axis value by the offset x (ox) value above
     for i=0, 10 do
        tpt.create(x + i, y, "WATR") --create a water particle
     end
  
     x = x + ox
     for i=0, 10 do
        tpt.create(x + i, y, "SALT")
     end
  
     x = x + ox
     for i=0, 10 do
        tpt.create(x + i, y, "OIL")
     end
  
     return false
  end
  
  -- Register the step function ClassicPowder. This will make the ClassicPowder function run every tick of Powder Toy.
  tpt.register_step(ClassicPowder)