Object Functions: Level and Object Manipulation

Object Manipulation

Querying Objects

• get_object(level, string label) -> object|null — Returns the object that is present in the given level that has the given label, or null if it could not be found.
• get_object_or_die(level, string label) -> object — Returns the object that is present in the given level that has the given label. If it cannot find any such object, it will immediately assert the game.
• get_objects_at_point(x, y) -> [object]|null — Returns all objects which intersect the specified x,y point, in absolute Level-coordinates.

Instantiating Objects

• object(string type_id, int midpoint_x, int midpoint_y, int facing, (optional) map properties) -> object — constructs and returns a new object. Note that the difference between this and spawn is that spawn returns a command to actually place the object in the level. object only creates the object and returns it. It may be stored for later use.
• object_playable(string type_id, int midpoint_x, int midpoint_y, int facing, (optional) map properties) -> object — constructs and returns a new object. Note that the difference between this and spawn is that spawn returns a command to actually place the object in the level. object_playable only creates the playble object and returns it. It may be stored for later use.
• is_object(string type_id) — returns true if you can construct this type_id with object().

Adding and Removing Objects

• add_object(object) — inserts the given object into the level. The object should not currently be present in the level. The position of the object is tweaked to make sure there are no solid overlaps, however if it is not possible to reasonably place the object without a solid overlap, then the object will not be placed and the object and caller will both receive the event add_object_fail.
• remove_object(object) — removes the given object from the level. If there are no references to the object stored, then the object will immediately be destroyed. However it is possible to keep a reference to the object and even insert it back into the level later using add_object()

Convenience Functions

• spawn(string type_id, int midpoint_x, int midpoint_y, int facing | {variables:values}, (optional) commands [cmd]) — Will create a new object of type given by type_id with the given midpoint and facing. Immediately after creation the object will have any commands given by cmd executed on it. You can reference the spawned object with {{{child}}} here. The child object will have the spawned event sent to it, and the parent object will have the child_spawned event sent to it. Note: A similar effect may be achieved with {{{add_object(object(…))}}}, which is useful if you want to pull out the reference to the object for something else - or insert the object from a variable.
• spawn_player(string type_id, int midpoint_x, int midpoint_y, int facing, (optional) list of commands cmd) — identical to spawn except that the new object is playable.

Collision and Tile Introspection

Tile Querying

• pixel_to_tile_coords(args) -> [x,y] — Gets the tile at the pixel position given in the arguments. The positioncan either be a single list of two values such as [x,y] or two seperate x,y co-ordinates.
• tile_to_pixel_coords(x, y, (opt)string) -> [x,y] — Gets the center pixel co-ordinates of a given tile co-ordinate. String can be effect the co-ordinates returned. "bounding" -> [x,y,w,h] Bounding rect of the tile. "center" -> [x,y] center co-ordinates of the tile(default)"hex" -> [[x0,y0],[x1,y1],[x2,y2],[x3,y3],[x4,y4],[x5,y5]] Co-ordinates of points around outside of the tile.
• tiles_at(x, y) -> [tile_object] — Gives a list of the tiles at the given x, y position. A tile_object has id, info, damage, friction, traction.

Non-solid Collisions

• collides(object a, string area_a, object b, string area_b) -> boolean returns true if area_a within object a collides with area_b within object b.

Solidity/Position Manipulation

• set_solid(x1, y1, x2, y2, boolean is_solid=false) — modifies the solidity of the level such that the rectangle given by (x1, y1, x2, y2) will have its solidity set to the value of is_solid
• move_to_standing() — tries to move the object downwards if it's in the air, or upwards if it's in solid space, until it's standing on solid ground.
• resolve_solid(object, int xdir, int ydir, int max_cycles=100) — will attempt to move the given object in the direction indicated by xdir/ydir until the object no longer has a solid overlap. Gives up after max_cycles. If called with no arguments other than the object, will try desperately to place the object in the level.

Solidity/Collision

• solid(level, int x, int y, (optional)int w=1, (optional) int h=1, (optional) null|[string] dimensions) -> boolean — returns true iff the level contains solid space within the given (x,y,w,h) rectangle. The final parameter allows you to search for solid rectangles generated by objects, as well as those generated by terrain - by default the game will only detect solid pixels generated by terrain. By providing a solid_dimension, it will find any pixels of solidity which objects are projecting into that dimension, allowing you to use this to detect objects that are being used as terrain.

  Tips: typically this will get used with a find function, in a form like the following: find(range(search_length), solid(level, u, v + value, 1, 1))

  That would, for example, give you the distance from whatever u,v point is (typically an object's midpoint), to the ground. Because it uses the find() function, it stops searching the moment it encounters solid ground.

  Warning: The solid_dimension parameter has been carefully optimized to be fast if and only if the string for the dimension is provided by a constant. When using this, you're encouraged to inline the string right in the call site for the function - i.e. solid(level, my_x, my_y, 1, 1, ['player']). Do not refer to a property to get this string, because the lookup cost for accessing that property will occur for every pixel that gets tested, which will butcher performance.

• point_solid(level, object, int x, int y) -> boolean — Tells if you a point is solid (or standable) from the perspective of the object that's provided as a parameter. Unlike solid(level), you cannot specify the solidity dimension - it uses the default solidity dimension.

• object_can_stand(Level, object, int x, int y) -> boolean — returns true iff the given point is standable from the perspective of the object that's provided as a parameter.

• standable(level, int x, int y, (optional)int w=1, (optional) int h=1) -> boolean — returns true iff the level contains standable space within the given (x,y,w,h) rectangle

• find_first_solid_point_on_line(level, object, int x1, int y1, int x2, int y2, int step_size) -> [x,y]|none — Return the first point along the line from x1 to y1 that is solid, from the point of the object in the level. Inverse of find_first_open_point_on_line. See also: point_solid.

• find_first_solid_point_on_line(level, object, int x1, int y1, int x2, int y2, int step_size) -> [x,y]|none — Return the first point along the line from x1 to y1 that is not solid, from the point of the object in the level. Inverse of find_first_solid_point_on_line.

• find_point_object_can_stand_on(Level, object, int x, int y, int dx, int dy, (optional) int max_search=1000) -> [int,int]|null — returns the first point that an object can stand on, starting at [x,y] and incrementing by [dx,dy] until the point is found.

• collides_with_level(object) -> boolean — returns true if the given object collides with the level.

##Miscellaneous

Camera Management

• scroll_to(object target) — scrolls the screen to the target object

Level-wide Visual FX

• shake_screen(int x_offset, int y_offset, int x_velocity, int y_velocity) — makes the screen camera shake
• screen_flash(list int[4] color, (optional) list int[4] delta, int duration) — flashes the screen the given color, and keeps the flash going for duration cycles. If delta is given, the color of the flash will be changed every cycle until the duration expires.

Global Player-Tracking

• achievement(id) — unlocks the achievement with the given id

Water

• add_water(int x1, int y1, int x2, int y2, (optional)[r,g,b,a]=[70,0,0,50]) — Put a rectangle of fluid on the level. There is a water controller object in Frogatto than wraps this up nicely as well. There's also an acid controller which adds some danger!
• add_wave(int x, int y, int xvelocity, int height, int length, int delta_height, int delta_length) — will add a wave with the given characteristics at the surface of the water above the (x,y) point. (x,y) must be within a body of water. Waves are a visual effect only and may not display at all on slower devices.
• remove_water(int x1, int y1, int x2, int y2) — Get rid of all the fluid inside a rectangular area. This can be used with add_water() to create non-rectangular shapes.

Currents

• radial_current(int intensity, int radius) -> uninspectable current object — Creates a current generator with the given intensity and radius. Will not have an effect until set() as an object's current_generator. See also: rect_current.
• rect_current(int x, int y, int w, int h, int x_velocity, int y_velocity, int strength) -> uninspectable current object — Creates a current generator object that has a current with the given parameters. Set the return value of this function to an object's current_generator to attach it to an object and thus place it in the level. See also: radial_current.

Repeating Level Segments

• add_level_module(string lvl, int x_offset, int y_offset) — adds the level module with the given level id at the given offset
• remove_level_module(string lvl) — removes the given level module

Level Overflow Management

• cosmic_shift(int x_offset, int y_offset) — adjust position of all objects and tiles in the level by the given offset

Grouping

• set_group(optional int group_id) — sets the current object to have the given group id, or to be in no group if group_id is not given
• group_size(level, int group_id) -> int — gives the number of objects in the object group given by group_id