Lua Functions in Jacob1's Mod

From The Powder Toy
Revision as of 16:10, 15 May 2013 by jacob1 (talk | contribs) (fix stamp_save return value)
Jump to: navigation, search

Note: to detect if someone is using this mod, use tpt.version.jacob1s_mod to get the major version number.

There are some general lua improvements I made in my mod:

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.

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)

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)

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"

tpt.sound(string filename)

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

Resets the pressure on the entire screen, like '=' was pressed

tpt.reset_pressure()

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

tpt.reset_temp()

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.

tpt.get_pressure(number x, number y)

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.

tpt.get_aheat(number x, number y)

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

tpt.get_velocity(string direction, number x, number y)

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.

tpt.get_gravity(number x, number y, string direction)

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

tpt.get_wall(number x, number y)

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.

tpt.create_wall(number id, number x, number y)

tpt.create_wall(string name, number x, number y)

tpt.clear_sim

Clears the sim, just like the button was pressed

tpt.clear_sim()

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.

tpt.reset_elements()

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, int (0 or 1) indestructible)

tpt.indestructible(string name)

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

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.

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)

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.

tpt.create_parts(number x, number y, number rx, number ry, number c, int (0 or 1) fill, number brush, number flags)

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

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)

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

tpt.floodfill(number x, number y, number c)

tpt.floodfill(number x, number y, number c, number cm, number bm, number flags)

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 10 letter stamp name of the stamp created.

tpt.save_stamp(number x, number y, number w, number h)

tpt.load_stamp

Loads a stamp and places it at (x, y). You may either pass in the value returned by tpt.save_stamp which is the 10 letter name stored in stamps.def, the the full filename/path to the stamp to load, 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

tpt.load_stamp(string filename, number x, number y)

tpt.load_stamp(string name, number x, number y)

tpt.load_stamp(number id, number x, number y)

tpt.set_selected

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.

tpt.set_selected(number sl, number sr, number SLALT)

tpt.set_decocol

Sets the current decoration color. Pass in either a hex number, or the 4 color arguments.

tpt.set_decocol(number hexcol)

tpt.set_decocol(number r, number g, number b, number a)

tpt.outside_airtemp

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.

tpt.outside_airtemp(number newtemp)