Difference between revisions of "Lua Functions in Jacob1's Mod"

From The Powder Toy
Jump to: navigation, search
m (add version constants info)
(remove tpt.sound, add sim.stickman)
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
Note: to detect if someone is using this mod, use tpt.version.jacob1s_mod to get the major version number.
+
First, there are some general lua improvements I made in my mod:
  
−
There are some general lua improvements I made in my mod:
+
Press tab to autocomplete most lua function names. This is helpful if you forgot the name of one but at least know how it starts.
  
−
Press tab to autocomplete any lua function name. This is helpful if you forgot the name of one but at least know how it starts.
+
Lua code can also be included inside of saves to be ran on open (if the user clicks yes). Click the LUA button in the FAV2 menu, and it will read the file "luacode.txt" and save it. When loading a save, the code is written to "newluacode.txt", and then a prompt comes up asking if you want to run the code. The code is executed in a lua sandbox, so it can't touch any files on your computer or send anything to the internet. At worst, it will exit or crash the game. See the readme for more info.
−
 
 
−
Almost all lua functions that set a property, ex. tpt.setfpscap or tpt.set_pressure, also have a get function. Just don't pass in any arguments to the set function to get the value instead, ex. tpt.set_pause() would return whether the game i paused or not. Adding in tons of get functions would be too complicated and long to do, this way is easier. An exception to this is the functions like tpt.get_pressure where I already added in a separate function.
 
−
 
 
−
Lua code can also be included inside of saves to be ran on open (if the user clicks yes). Click the LUA button in the FAV2 menu, and it will read the file "luacode.txt" and save it. When loading a save, the code is written to "newluacode.txt", and then a prompt comes up asking if you want to run the code. The code is executed in a lua sandbox, so it can't touch any files on your computer or send anything to the internet. At worst, it will exit or crash the game.
 
  
 
To detect the mod, use tpt.version.jacob1s_mod to get the current version number. Other version numbers you can use are tpt.version.jacob1s_mod_minor (minor version), tpt.version.jacob1s_mod_save (saving code version), and tpt.version.jacob1s_mod_build (build number that's used in updates)
 
To detect the mod, use tpt.version.jacob1s_mod to get the current version number. Other version numbers you can use are tpt.version.jacob1s_mod_minor (minor version), tpt.version.jacob1s_mod_save (saving code version), and tpt.version.jacob1s_mod_build (build number that's used in updates)
  
−
For the new functions, I made all of ones listed below. I plan to add some to tpt++ in different api's sometime (already started on some)
+
Below is the list of new functions I added. Note that most of the new functions were removed in version 30 because they were just duplicates of things the new official APIs can do.
−
 
 
−
===  tpt.sound  ===
 
−
Play a sound just like !sound file.wav will do. It has to be a .wav
 
−
 
 
−
It will return an error if it can't find an audio device, you must launch tpt with the argument "sound"
 
−
 
 
−
<code>tpt.sound(string filename)</code>
 
  
 
===  tpt.load  ===
 
===  tpt.load  ===
Line 29: Line 18:
  
 
<code>tpt.bubble(number x, number y)</code>
 
<code>tpt.bubble(number x, number y)</code>
−
 
−
===  tpt.reset_pressure  ===
 
−
Resets the pressure on the entire screen, like '=' was pressed
 
−
 
−
<code>tpt.reset_pressure()</code>
 
−
 
−
===  tpt.reset_temp  ===
 
−
Just like !reset temp, it will reset the temperature of everything to it's default value. Note: This will also reset wifi's temp
 
−
 
−
<code>tpt.reset_temp()</code>
 
−
 
−
===  tpt.get_pressure  ===
 
−
Gets the pressure at a coordinate. The coordinates are on the CELL grid, so divide the x and y arguments by 4 before you call this, or else you might get an out of range error.
 
−
 
−
<code>tpt.get_pressure(number x, number y)</code>
 
−
 
−
===  tpt.get_aheat  ===
 
−
Gets the ambient heat at a coordinate. This works just like the pressure and wall grids, so divide the coordinates by 4.
 
−
 
−
<code>tpt.get_aheat(number x, number y)</code>
 
−
 
−
===  tpt.get_velocity  ===
 
−
Gets the velocity at a coordinate. This is not a particle's velocity, this is what is seen when you press 1, the velocity of the air.
 
−
 
−
For the direction argument, pass in either "x" or "y" depending on whether you want vx or vy
 
−
 
−
<code>tpt.get_velocity(string direction, number x, number y)</code>
 
−
 
−
===  tpt.get_gravity  ===
 
−
Gets the Newtonian gravity at a coordinate. Newtonian gravity is also on a CELL grid. direction should be either "x" or "y". If you want to get the total Newtonian gravity at a point, that doesn't work for some reason, so it always returns 0. That will happen if you don't pass in a direction argument.
 
−
 
−
<code>tpt.get_gravity(number x, number y, string direction)</code>
 
  
 
===  tpt.maxframes  ===
 
===  tpt.maxframes  ===
Line 66: Line 23:
  
 
<code>tpt.maxframes(number newmaxframes)</code>
 
<code>tpt.maxframes(number newmaxframes)</code>
−
 
−
===  tpt.get_wall  ===
 
−
Works exactly like tpt.get_wallmap, which is apparently undocumented. But I did it first. Since Simon's was exactly the same, I just aliased mine to it. Remember that walls are on a 4x4 grid, so divide coordinates by 4.
 
−
 
−
<code>tpt.get_wall(number x, number y)</code>
 
−
 
−
===  tpt.create_wall  ===
 
−
Works exactly like tpt.set_wallmap, except I did it first. This one uses my version of the function, which has some extra features. Simon's version is also aliased to this one. You can either pass in a wall id, found in powder.h, or pass in it's name, also found there but can easily be seen in my mod's HUD. Don't use the names found in tpt++'s HUD, the names in my mod are slightly different. And again, walls are on a 4x4 grid.
 
−
 
−
It will give an error if you try to create an invalid wall id, this also includes things that are technically walls like HEAT and COOL, they won't work.
 
−
 
−
<code>tpt.create_wall(number id, number x, number y)
 
−
 
−
tpt.create_wall(string name, number x, number y)</code>
 
−
 
−
===  tpt.clear_sim  ===
 
−
Clears the sim, just like the button was pressed
 
−
 
−
<code>tpt.clear_sim()</code>
 
−
 
−
===  tpt.reset_elements  ===
 
−
If you have many element scripts loaded, or did something with tpt.el., and you want to reverse this change, this function will do that. All elements will go back to their defaults.
 
−
 
−
<code>tpt.reset_elements()</code>
 
  
 
===  tpt.indestructible  ===
 
===  tpt.indestructible  ===
Line 96: Line 29:
 
<code>tpt.indestructible(number elementid)
 
<code>tpt.indestructible(number elementid)
  
−
tpt.indestructible(number elementid, int (0 or 1) indestructible)
+
tpt.indestructible(number elementid, bool (0 or 1) indestructible)
  
 
tpt.indestructible(string name)
 
tpt.indestructible(string name)
  
−
tpt.indestructible(string name, int (0 or 1) indestructible)</code>
+
tpt.indestructible(string name, bool (0 or 1) indestructible)</code>
−
 
 
−
===  tpt.moving_solid  ===
 
−
Makes an element behave like a moving solid. Yes, this is real. Also, it's status like this will be saved in saves, but it persists forever or until you do tpt.reset_elements() or pass in 0 as the second argument to this. The second argument is optional, just like the function above. By default, if it isn't provided, it will always do on, just like before.
 
−
 
 
−
<code>tpt.moving_solid(number elementid)
 
−
 
 
−
tpt.moving_solid(number elementid, int (0 or 1) moving?)
 
−
 
 
−
tpt.moving_solid(string name)
 
−
 
 
−
tpt.moving_solid(string name, int (0 or 1)moving)</code>
 
−
 
 
−
===  tpt.create_parts  ===
 
−
Basically just calls create_parts how tpt would. x and y are the center coordinates. rx and ry would be the brush radius. c is the type to create. fill determines whether it will fill in the circle or make it hollow. You probably want 1. Brush is the brush type, defaulting to circle brush. 0 is Circle, 1 for square, and 2 for triangle. Flags defaults to the current flag (replace mode, specific delete) variables, use 0 to ensure normal drawing though.
 
−
 
 
−
<code>tpt.create_parts(number x, number y, number rx, number ry, number c, int (0 or 1) fill, number brush, number flags)</code>
 
−
 
 
−
===  tpt.create_line  ===
 
−
Basically just calls create_line how tpt would. See above for details on all the arguments. The only difference is that you need the (x1,y1) and (x2,y2) coordinates instead of just (x,y) now
 
−
 
 
−
<code>tpt.create_line(number x1, number y1, number x2, number y2, number rx, number ry, number c, int (0 or 1) fill, number brush, number flags)</code>
 
−
 
 
−
===  tpt.floodfill  ===
 
−
Basically just calls flood_parts how tpt would. x and y are the coordinates to flood at. c is the particle id to flood. I'm not completely sure what cm and bm are, so I would just stop at this point. They default to -1, and the function decides what they should be itself this way. Flags is the same as anything else, it just affects how particles are created. It defaults to the current flags
 
−
 
 
−
<code>tpt.floodfill(number x, number y, number c)
 
−
 
 
−
tpt.floodfill(number x, number y, number c, number cm, number bm, number flags)</code>
 
−
 
 
−
===  tpt.save_stamp  ===
 
−
Pass in the coordinates to save the stamp at, and it will be saved. They are not CELL coordinates, just normal ones.
 
−
It returns the full filename of the stamp created.
 
  
−
<code>tpt.save_stamp(number x, number y, number w, number h)</code>
+
===  tpt.oldmenu  ===
 +
Turns the old menu (press 'o') on or off. This changes the interface slightly and probably noone uses it but this function is here so things like the tptmp button can move automatically. With no arguments it returns whether the old menu is on or off currently.
  
−
===  tpt.load_stamp  ===
+
<code>tpt.oldmenu(bool (0 or 1) setting)
−
Loads a stamp and places it at (x, y). You may either pass in the value returned by tpt.save_stamp which is the full filename, the 10 letter stamp name (name starts with the letters 4e - 50 usually) that is displayed in the browser, or just a stamp id, where the first stamp you see in the browser is id 1.
 
  
−
It returns whether the save was loaded properly, but it probably will load if the stamp exists
+
number tpt.oldmenu()</code>
  
−
<code>tpt.load_stamp(string filename, number x, number y)
+
=== gfx.tooltip ===
 +
Creates a tooltip on screen. It will instantly begin fading away unless you call this every frame, or set alpha to a number higher than 255 (in that case it will count down and only start fading away at 255).
  
−
tpt.load_stamp(string name, number x, number y)
+
ID sets the tooltip ID you want to modify (to modify normal game tooltips). Some tooltips have special code to handle them, but ID's 0 to 4 set the bottom left tooltip, the element tooltip, the center tooltip, the quickoptions tooltip, and the intro text tooltip respectively. Leaving it blank uses ID 5.
  
−
tpt.load_stamp(number id, number x, number y)</code>
+
Example to remove the intro text tooltip: gfx.toolTip("", 0, 0, 0, 4)
  
−
===  tpt.set_selected  ===
+
<code>gfx.tooltip(string tooltip, number x, number y, [number alpha], [number ID])</code>
−
Sets the currently selected elements. Use nil or just don't give an argument for anything you don't want to change. For example, tpt.set_selected(28) will set left selected to diamond but not change right selected (0 normally for erase) or alt selected.
 
  
−
<code>tpt.set_selected(number sl, number sr, number SLALT)</code>
+
=== sim.stickman ===
 +
Modifies or fetches stickman properties. Advanced function, directly modifies the stickman struct.
  
−
===  tpt.set_decocol  ===
+
<code>sim.stickman(num, property, [nil, offset])
−
Sets the current decoration color. Pass in either a hex number, or the 4 color arguments.
 
  
−
<code>tpt.set_decocol(number hexcol)
+
sim.stickman(num, property, value, [offset])
 +
</code>
  
−
tpt.set_decocol(number r, number g, number b, number a)</code>
+
num controls the stickman to modify. 1 for STKM, 2 for STKM2, and 3-102 for FIGH.
  
−
===  tpt.outside_airtemp  ===
+
property controls the property to get/set. Valid single options are "comm", "pcomm", "elem", "spwn", "frames", "spawnID", and "rocketBoots"<br/>
−
Sets the outside air temperature of ambient heat, what it changes to around the edges. Must be between 0 and 10000, use Kelvin for the temp.
+
Some properties are arrays. You can use offset to control the array index. Valid array properties are "legs" (0-15) and "accs" (0-7). If fetching a value, use nil for argument 3.
  
−
<code>tpt.outside_airtemp(number newtemp)</code>
+
argument 3 is the optional value to set. If not provided, it will return the current value instead.
  
 
[[Category:Lua]]
 
[[Category:Lua]]

Latest revision as of 22:14, 14 October 2017

First, there are some general lua improvements I made in my mod:

Press tab to autocomplete most lua function names. This is helpful if you forgot the name of one but at least know how it starts.

Lua code can also be included inside of saves to be ran on open (if the user clicks yes). Click the LUA button in the FAV2 menu, and it will read the file "luacode.txt" and save it. When loading a save, the code is written to "newluacode.txt", and then a prompt comes up asking if you want to run the code. The code is executed in a lua sandbox, so it can't touch any files on your computer or send anything to the internet. At worst, it will exit or crash the game. See the readme for more info.

To detect the mod, use tpt.version.jacob1s_mod to get the current version number. Other version numbers you can use are tpt.version.jacob1s_mod_minor (minor version), tpt.version.jacob1s_mod_save (saving code version), and tpt.version.jacob1s_mod_build (build number that's used in updates)

Below is the list of new functions I added. Note that most of the new functions were removed in version 30 because they were just duplicates of things the new official APIs can do.

tpt.load

Just like !load id, but in lua.

tpt.load(number id)

tpt.bubble

Just like !bubble x,y but in lua. Creates a SOAP bubble in a perfectly round shape

tpt.bubble(number x, number y)

tpt.maxframes

Sets the maximum number of frames ANIM can have. By default, it's 25 frames because saves get huge quickly, but you can change it with this. It must be between 1 and 256. This function will also reset all existing animations.

tpt.maxframes(number newmaxframes)

tpt.indestructible

Makes an element completely indestructible, like DMND. This will also prevent any state changes it has, or anything that tries to delete it like BHOL from doing that. The second argument is optional, but if that argument it 0, it will remove indestructible status from that element. And yes, it works on DMND too. The first can be either an id or name.

tpt.indestructible(number elementid)

tpt.indestructible(number elementid, bool (0 or 1) indestructible)

tpt.indestructible(string name)

tpt.indestructible(string name, bool (0 or 1) indestructible)

tpt.oldmenu

Turns the old menu (press 'o') on or off. This changes the interface slightly and probably noone uses it but this function is here so things like the tptmp button can move automatically. With no arguments it returns whether the old menu is on or off currently.

tpt.oldmenu(bool (0 or 1) setting)

number tpt.oldmenu()

gfx.tooltip

Creates a tooltip on screen. It will instantly begin fading away unless you call this every frame, or set alpha to a number higher than 255 (in that case it will count down and only start fading away at 255).

ID sets the tooltip ID you want to modify (to modify normal game tooltips). Some tooltips have special code to handle them, but ID's 0 to 4 set the bottom left tooltip, the element tooltip, the center tooltip, the quickoptions tooltip, and the intro text tooltip respectively. Leaving it blank uses ID 5.

Example to remove the intro text tooltip: gfx.toolTip("", 0, 0, 0, 4)

gfx.tooltip(string tooltip, number x, number y, [number alpha], [number ID])

sim.stickman

Modifies or fetches stickman properties. Advanced function, directly modifies the stickman struct.

sim.stickman(num, property, [nil, offset])

sim.stickman(num, property, value, [offset])

num controls the stickman to modify. 1 for STKM, 2 for STKM2, and 3-102 for FIGH.

property controls the property to get/set. Valid single options are "comm", "pcomm", "elem", "spwn", "frames", "spawnID", and "rocketBoots"
Some properties are arrays. You can use offset to control the array index. Valid array properties are "legs" (0-15) and "accs" (0-7). If fetching a value, use nil for argument 3.

argument 3 is the optional value to set. If not provided, it will return the current value instead.

Retrieved from "https://powdertoy.co.uk/Wiki/index.php?title=Lua_Functions_in_Jacob1%27s_Mod&oldid=6795"