Difference between revisions of "Lua"

From The Powder Toy
Jump to: navigation, search
(tpt.screenshot)
(Remove lots of stuff at the beginning and end + update some outdated info)
Line 3: Line 3:
 
----
 
----
  
'''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]] )
  
''!set type dust metl''
+
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/
 
 
The equivalent command in TPT's Lua is ''tpt.set_property("type", "metl", "dust")'' (see [[lua#tpt.set_property]] )
 
 
 
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. 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/
 
 
 
----
 
 
 
The new Lua Console now 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 easily.
 
 
 
This tutorial shows [[how to run a script]]
 
 
 
==  Variable Types  ==
 
<ins>The different variable types are:</ins>
 
 
 
 
 
* ''''string''''
 
 
 
Represents a word, character, or phrase. ''''string'''' variables must begin and end with double-quotes. (''"'')
 
 
 
'''Example:''' ''local str = "This is a string variable."''
 
 
 
 
 
 
 
* ''''number''''
 
 
 
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].)
 
 
 
'''Example:''' ''local num = 1234''
 
 
 
 
 
 
 
* ''''boolean''''
 
 
 
Represents a switch that is either on (true) or off (false).
 
 
 
'''Example:''' ''local bool = true''
 
 
 
 
 
* ''''function''''
 
 
 
Represents a method or function in lua.
 
 
 
'''Example:''' ''function func(arguments)''
 
 
 
'''NOTE:''' Functions that use a ''''function'''' as an argument do not include the () at the end. Only the name must be given.
 
 
 
 
 
 
 
* ''''table''''
 
 
 
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.
 
 
 
'''Example:''' ''local tbl = {}''
 
 
 
This creates a blank table.
 
 
 
 
 
 
 
'''Example:''' ''local tbl = {1, 2, 3, "string"}''
 
 
 
Creates a table with the elements 1, 2, 3 and "string".
 
 
 
You can call these variables in this manner:
 
 
 
 
 
  tbl[1] --returns 1
 
  tbl[2] --returns 2
 
  tbl[3] --returns 3
 
  tbl[4] --returns "string"
 
 
 
 
 
 
 
'''Example:'''
 
 
 
  local tbl = {}
 
  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.
 
 
 
You can call these variables in this manner:
 
 
 
  tbl.x --returns 7
 
  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. )
 
 
 
 
 
 
 
* ''''object''''
 
 
 
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.
 
 
 
==  General Arguments  ==
 
<ins>The arguments given here are general, here are some examples:</ins>
 
 
 
 
 
''''string'' '''property'''''
 
 
 
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. (''"'')
 
The different available properties are:
 
 
 
  "type"
 
  "life"
 
  "ctype"
 
  "temp"
 
  "tmp"
 
  "tmp2"
 
  "vx"
 
  "vy"
 
  "x"
 
  "y"
 
  "dcolour"
 
 
 
Any other given strings will result with an invalid property error.
 
 
 
 
 
 
 
''''object'' '''value'''''
 
 
 
What you are setting the current property to. Since this is an '''object''' variable, it's type will depend on the function.
 
 
 
 
 
 
 
''''string'' '''type'''''
 
 
 
A ''''string'''' which is the code-name of an element "dust" "watr" "spng".
 
 
 
 
 
''''number'' '''index'''''
 
 
 
A specific particle number by it's index.
 
 
 
 
 
 
 
''''number'' '''state'''''
 
 
 
0 or 1, 0 for off, 1 for on.
 
 
 
 
 
 
 
''''number'' '''Width''''' and ''''number'' '''Height'''''
 
 
 
Represent a rectangle.
 
 
 
 
 
 
 
''''number'' '''x''''' and ''''number'' '''y'''''
 
 
 
Represents a 2-Dimensional coordinate.
 
 
 
 
 
 
 
''''string'' '''text'''''
 
 
 
Represents text
 
 
 
 
 
 
 
''''number'' '''toggle'''''
 
 
 
Represents either 1 for on or 0 for off
 
 
 
 
 
 
 
''''number'' '''menu'''''
 
 
 
Represents a menu, eg 1 = Walls, 2 = Electronics
 
 
 
 
 
 
 
''''number'' '''display'''''
 
 
 
Represents a display mode, eg 4 = Fire, 6 = Heat
 
  
 +
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 [[how to run a script]]
  
 
=  Lua API  =
 
=  Lua API  =
Line 191: Line 15:
  
 
==  Game  ==
 
==  Game  ==
 
 
  
 
===  tpt.set_pause  ===
 
===  tpt.set_pause  ===
Line 207: Line 29:
  
 
Get if the game is paused currently: <code>tpt.set_pause() == 1</code>
 
Get if the game is paused currently: <code>tpt.set_pause() == 1</code>
 
 
  
 
===  tpt.set_console  ===
 
===  tpt.set_console  ===
Line 223: Line 43:
  
 
Get if the console is currently open: <code>tpt.set_console() == 1</code>
 
Get if the console is currently open: <code>tpt.set_console() == 1</code>
 
 
  
 
===  tpt.set_shortcuts  ===
 
===  tpt.set_shortcuts  ===
Line 241: Line 59:
  
 
Get if keyboard shortcuts are currently disabled: <code>tpt.set_shortcuts(-1) == 1</code>
 
Get if keyboard shortcuts are currently disabled: <code>tpt.set_shortcuts(-1) == 1</code>
 
 
  
 
===  tpt.set_gravity  ===
 
===  tpt.set_gravity  ===
Line 261: Line 77:
  
 
Set the entire stage's gravity to 1000: <code>tpt.set_gravity(nil, nil, nil, nil, 1000)</code>
 
Set the entire stage's gravity to 1000: <code>tpt.set_gravity(nil, nil, nil, nil, 1000)</code>
 
 
  
 
===  tpt.reset_gravity_field  ===
 
===  tpt.reset_gravity_field  ===
Line 281: Line 95:
  
 
Reset gravity from (100,100) to (300,300): <code>tpt.reset_gravity_field(100, 100, 200, 200) </code>
 
Reset gravity from (100,100) to (300,300): <code>tpt.reset_gravity_field(100, 100, 200, 200) </code>
 
 
  
 
===  tpt.set_pressure  ===
 
===  tpt.set_pressure  ===
Line 301: Line 113:
  
 
Set pressure everywhere to 200: <code>tpt.set_pressure(nil,nil,nil,nil,200)</code>
 
Set pressure everywhere to 200: <code>tpt.set_pressure(nil,nil,nil,nil,200)</code>
 
 
  
 
===  tpt.reset_velocity  ===
 
===  tpt.reset_velocity  ===
Line 319: Line 129:
  
 
Reset velocity in the point (100,100): <code>tpt.reset_velocity(100,100,1,1)</code>
 
Reset velocity in the point (100,100): <code>tpt.reset_velocity(100,100,1,1)</code>
 
 
  
 
===  tpt.hud  ===
 
===  tpt.hud  ===
Line 329: Line 137:
  
 
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.
 
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  ===
Line 341: Line 147:
  
 
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.
 
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  ===
Line 350: Line 155:
  
 
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.
 
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  ===
Line 360: Line 163:
  
 
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.
 
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  ===
Line 372: Line 173:
  
 
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.  
 
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  ===
Line 381: Line 180:
 
Changes activated menu. If you don't pass in any arguments, the command will return the currently active 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 in the quick Lua reference [[http://boxmein.x10.mx/tptelements/lua-reference.html#elem.SC_WALL]], but otherwise range from 0 (SC_WALL) to 14 (SC_DECO) from the top downward, so the walls menu will be 0 and the decorations menu will be 14.
+
The menu IDs are detailed here: [[Element_Properties#Menu_sections]]
 
 
  
 +
Example: <code>tpt.active_menu(elem.SC_EXPLOSIVE)</code>
  
 
===  tpt.display_mode  ===
 
===  tpt.display_mode  ===
Line 406: Line 205:
 
9 = Heat Gradient<br>
 
9 = Heat Gradient<br>
 
10 = Life Gradient<br>
 
10 = Life Gradient<br>
 
 
 
  
 
===  tpt.setfpscap  ===
 
===  tpt.setfpscap  ===
Line 419: Line 215:
  
 
If you don't pass in any arguments, it will return the current fps cap.
 
If you don't pass in any arguments, it will return the current fps cap.
 
 
  
 
===  tpt.setfire  ===
 
===  tpt.setfire  ===
Line 426: Line 220:
  
 
<code>tpt.setfire(number strength)</code>
 
<code>tpt.setfire(number strength)</code>
 
 
  
 
===  tpt.setwindowsize  ===
 
===  tpt.setwindowsize  ===
Line 472: Line 264:
 
</code>
 
</code>
  
===  object tpt.get_property  ===
+
===  tpt.get_property  ===
Get various properties of a particle. Returns an ''object''
+
Returns various properties of a particle.
  
 
<code>
 
<code>
Line 502: Line 294:
 
<code>tpt.start_getPartIndex()</code>
 
<code>tpt.start_getPartIndex()</code>
  
===  boolean tpt.next_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)
 
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)
  
 
<code>tpt.next_getPartIndex()</code>
 
<code>tpt.next_getPartIndex()</code>
  
===  number tpt.getPartIndex  ===
+
===  tpt.getPartIndex  ===
 
Get the current index iterator.
 
Get the current index iterator.
  
Line 523: Line 315:
 
</pre>
 
</pre>
  
===  number tpt.get_numOfParts  ===
+
These functions are made obsolete by the function sim.parts(). That allows you to use Lua's iterators.
*Returns the number of particles currently on the screen.
+
 
 +
===  tpt.get_numOfParts  ===
 +
Returns the number of particles currently on the screen.
  
 
<code>tpt.get_numOfParts()</code>
 
<code>tpt.get_numOfParts()</code>
  
 +
A newer way to get this is the variable sim.NUM_PARTS
  
 
==  Drawing  ==
 
==  Drawing  ==
  
===  number tpt.textwidth  ===
+
===  tpt.textwidth  ===
Measures (in pixels) the width of a given ''string''. Returns a ''number''
+
Measures (in pixels) the width of a given string. Returns a number.
  
 
<code>tpt.textwidth(string text)</code>
 
<code>tpt.textwidth(string text)</code>
Line 607: Line 402:
 
<code>tpt.message_box(string title, string message)</code>
 
<code>tpt.message_box(string title, string message)</code>
  
===  string tpt.input  ===
+
===  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).
  
Line 615: Line 410:
 
tpt.input(string title, string message, string text)
 
tpt.input(string title, string message, string text)
 
</code>
 
</code>
 +
 +
===  tpt.throw_error  ===
 +
Displays an error message box.
 +
 +
<code>tpt.throw_error(string text)</code>
  
 
==  Events  ==
 
==  Events  ==
Line 620: Line 420:
 
===  tpt.register_step  ===
 
===  tpt.register_step  ===
 
Register a function to be run on every frame
 
Register a function to be run on every frame
You may only have 6 step functions registered at once
 
  
 
<code>tpt.register_step(function func)</code>
 
<code>tpt.register_step(function func)</code>
Line 631: Line 430:
 
===  tpt.register_mouseclick  ===
 
===  tpt.register_mouseclick  ===
 
Register a function to be run every time the mouse clicks.
 
Register a function to be run every time the mouse clicks.
You may only have 6 mouseclick functions registered at once
 
  
 
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.
 
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.
  
Passes: (''number mousex, number mousey, number button, number event'')
+
Function arguments: mousex, mousey, button, event
  
 
<code>tpt.register_mouseclick(function func)</code>
 
<code>tpt.register_mouseclick(function func)</code>
Line 646: Line 444:
 
===  tpt.register_keypress  ===
 
===  tpt.register_keypress  ===
 
Register a function to be run every time a key is pressed.
 
Register a function to be run every time a key is pressed.
You may only have 6 keypress functions registered at once
 
  
 
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.
 
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.
  
Passes: (''string key, number key, number modifier, number event'')
+
Function arguments: key, nkey, modifier, event
  
 
<code>tpt.register_keypress(function func)</code>
 
<code>tpt.register_keypress(function func)</code>
Line 658: Line 455:
  
 
<code>tpt.unregister_keypress(function func)</code>
 
<code>tpt.unregister_keypress(function func)</code>
 
 
  
 
==  Misc  ==
 
==  Misc  ==
  
===  string tpt.get_name  ===
+
===  tpt.get_name  ===
Get the current username, returns a ''string''
+
Returns the current username.
  
 
<code>tpt.get_name()</code>
 
<code>tpt.get_name()</code>
 
===  tpt.throw_error  ===
 
Displays an error message
 
 
<code>tpt.throw_error(string text)</code>
 
  
 
===  tpt.setdebug  ===
 
===  tpt.setdebug  ===
Sets the "debug mode". Setting it to 1, or an odd number, will display info on the number of particles on the screen. Setting it to 4 or 5 will display useful information when you draw lines using shift.  
+
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.  
This function is depreciated in tpt++ (and has no replacement yet)
 
  
 
<code>tpt.setdebug(number mode)</code>
 
<code>tpt.setdebug(number mode)</code>
  
 
===  tpt.element  ===
 
===  tpt.element  ===
returns an element's number. For example, it would return 28 for dmnd
+
Returns an element's number. For example, it would return 28 for dmnd. If passed a number it will return the name instead.
 +
 
 +
<code>tpt.element(string elementname)
  
<code>tpt.element(string elementname)</code>
+
tpt.element(number elementid)</code>
  
 
===  tpt.element_func  ===
 
===  tpt.element_func  ===
 
allows you to replace or add on to an element's update function. Write a function like normal, and then put its name into this command. Use tpt.element("...") or tpt.el.dust.id for el_number, and make replace true if you want to overwrite the previous function, or false instead.  
 
allows you to replace or add on to an element's update function. Write a function like normal, and then put its name into this command. Use tpt.element("...") or tpt.el.dust.id for el_number, and make replace true if you want to overwrite the previous function, or false instead.  
  
Passes: (''number index, number partx, number party, number surround_space, number nt'')
+
Function arguments: index, x, y, surround_space, nt
  
 
Returns: return 1 from your function if the particle is killed.
 
Returns: return 1 from your function if the particle is killed.
Line 696: Line 487:
  
 
===  tpt.graphics_func  ===
 
===  tpt.graphics_func  ===
allows you to replace an element's graphics function. Write a function like normal, and then put its name into this command. Use tpt.el.(name of element to change).id for el_number.
+
Allows you to replace an element's graphics function. Write a function like normal, and then put its name into this command. Use tpt.el.(name of element to change).id for el_number.
  
Passes: (''number index, number colr, number colg, number colb'')
+
Function arguments: index, colr, colg, colb
  
 
Returns: cache, pixel_mode, cola, colr, colg, colb, firea, firer, fireg, and fireb.
 
Returns: cache, pixel_mode, cola, colr, colg, colb, firea, firer, fireg, and fireb.
  
set cache to 1 if you don't want the function to ever be called again, preventing lag. Don't do this if you need the way your element looks to change depending on its properties.
+
Set cache to 1 if you don't want the function to ever be called again, preventing lag. Don't do this if you need the way your element looks to change depending on its properties.
  
 
colr/g/b are the red, green, and blue colors of your element. firea/r/g/b set the fire colors, but pixel_mode needs to be set to 0x00022000 for them to work.
 
colr/g/b are the red, green, and blue colors of your element. firea/r/g/b set the fire colors, but pixel_mode needs to be set to 0x00022000 for them to work.
 
There is currently a glitch with this, it may crash the game if the function has an error.
 
  
 
<code>tpt.graphics_func(function newfunction, number el_number)</code>
 
<code>tpt.graphics_func(function newfunction, number el_number)</code>
Line 769: Line 558:
  
 
<code>tpt.set_clipboard(string text)</code>
 
<code>tpt.set_clipboard(string text)</code>
 
=  Mods with Lua Functions  =
 
=== Jacob1's Mod ===
 
 
Jacob1's Mod adds many new lua functions and features besides just new functions, like auto-completion with tab in the console. For a full list and descriptions, see [[Lua_Functions_in_Jacob1%27s_Mod|This page]]
 
 
===  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 ====
 
These are all in the official version now, except for tpt.set_glow was renamed tpt.set_fire
 
* tpt.throw_error(string error)
 
 
* tpt.getscript(string script)
 
 
* tpt.hud(number state)
 
 
* tpt.newtonian_gravity(number state)
 
 
* tpt.ambient_heat(number state)
 
 
* tpt.decorations_enable(number state)
 
 
* tpt.heat(number state)
 
 
* tpt.active_menu(number menu)
 
 
* tpt.display_mode(number display)
 
 
* tpt.set_glow(number fireintensity)
 
  
 
=  Simple Example Code  =
 
=  Simple Example Code  =
Line 823: Line 567:
 
    
 
    
 
   -- Here we define our main function for the script
 
   -- Here we define our main function for the script
   function ClassicPowder()
+
   local function ClassicPowder()
 
     local ox = 125 -- This will be our offset for the different elements we will create.
 
     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 y = 4 -- where on the y (vertical) axis where we will create our elements.

Revision as of 04:23, 29 October 2014

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 how to run a script

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

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 at point (150, 150): tpt.set_gravity(150, 150)

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

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 at point (150, 150): tpt.reset_gravity_field(150, 150)

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

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 at (100,100) (for a 1x1 rectangle to only use one wallpixel) to 200: tpt.set_pressure(100,100,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 point (100,100): tpt.reset_velocity(100,100,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.display_mode

tpt.display_mode(number display)

Changes activated display mode.

There's 11 display modes, detailed here [[1]], but I'll provide a reference below:

Display Modes

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

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.

tpt.setfire

Changes the strength of the games 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()

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.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)

Events

tpt.register_step

Register a function to be run on every frame

tpt.register_step(function func)

tpt.unregister_step

Unregister a previously registered function

tpt.unregister_step(function func)

tpt.register_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

tpt.register_mouseclick(function func)

tpt.unregister_mouseclick

Unregister a previously registered function

tpt.unregister_mouseclick(function func)

tpt.register_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

tpt.register_keypress(function func)

tpt.unregister_keypress

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.

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

allows you to replace or add on to an element's update function. Write a function like normal, and then put its name into this command. Use tpt.element("...") or tpt.el.dust.id for el_number, and make replace true if you want to overwrite the previous function, or false instead.

Function arguments: index, x, y, surround_space, nt

Returns: return 1 from your function if the particle is killed.

tpt.element_func(function newfunction, number el_number)

tpt.element_func(function newfunction, number el_number, boolean replace)

tpt.graphics_func

Allows you to replace an element's graphics function. Write a function like normal, and then put its name into this command. Use tpt.el.(name of element to change).id for el_number.

Function arguments: index, colr, colg, colb

Returns: cache, pixel_mode, cola, colr, colg, colb, firea, firer, fireg, and fireb.

Set cache to 1 if you don't want the function to ever be called again, preventing lag. Don't do this if you need the way your element looks to change depending on its properties.

colr/g/b are the red, green, and blue colors of your element. firea/r/g/b set the fire colors, but pixel_mode needs to be set to 0x00022000 for them to work.

tpt.graphics_func(function newfunction, number el_number)

The pixel mode values you can use are:

PMODE_NONE	0x00000000 --prevents anything from being drawn
PMODE_FLAT	0x00000001 --draw a basic pixel, overwriting the color under it. Doesn't support cola.
PMODE_BLOB	0x00000002 --adds a blobby effect, like you were using blob (5) display mode
PMODE_BLUR	0x00000004 --used in liquids in fancy display mode
PMODE_GLOW	0x00000008 --Glow effect, used in elements like DEUT and TRON in fancy display mode
PMODE_SPARK	0x00000010 -- used for things such as GBMB at first, dimmer than other modes
PMODE_FLARE	0x00000020 --BOMB and other similar elements, brighter than PMODE_SPARK
PMODE_LFLARE	0x00000040 --brightest spark mode, used when DEST hits something
PMODE_ADD	0x00000080 --like PMODE_FLAT, but adds color to a pixel, instead of overwriting it.
PMODE_BLEND	0x00000100 --basically the same thing as PMODE_ADD, but has better OpenGL support
PSPEC_STICKMAN	0x00000200 --does nothing, because the stickmen won't get drawn unless it actually is one

NO_DECO		0x00001000 --prevents decoration from showing on the element (used in LCRY)
DECO_FIRE	0x00002000 --Allow decoration to be drawn on using the fire effect (gasses have this set)

FIRE_ADD	0x00010000 --adds a weak fire effect around the element (ex. LAVA/LIGH)
FIRE_BLEND	0x00020000 --adds a stronger fire effect around the element, default for gasses

EFFECT_GRAVIN	0x01000000 --adds a PRTI effect. Might take some coding in an update function to get it to work properly, PRTI uses life and ctype to create the effects
EFFECT_GRAVOUT	0x02000000 --adds a PRTO effect. Might take some coding in an update function to get it to work properly, PRTI uses life and ctype to create the effects

You can combine them in any way you want, you probably need more than one anyway. Radioactive elements default to PMODE_FLAT+PMODE_GLOW, liquids to PMODE_FLAT+PMODE_BLUR, and gasses to FIRE_BLEND+DECO_FIRE, with a firea of 125 and firer/g/b of colr/g/b divided by 2

See this for a picture of what they look like: https://powdertoy.co.uk/Wiki/W/File:Particle_Drawing_Modes.png.html

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)

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)