Class l2df.class.component.physix.world

Last updated 2021-05-28 15:24:22

World component.

This would be suppressed and removed in future.

Inherited from l2df.class.Component class.

Info:

Functions

World:init([cellsize=64]) World initialization.
World:added(obj[, kwargs]) Component was added to Entity event.
World:removed(obj) Component was removed from Entity event.
World.getFromContext() Static function for getting current world in stack.
World:update(obj, dt, islast) Component post-update event handler.
World:liftdown(obj) Component liftdown event handler.
World:liftup(obj) Component liftup event handler.
World:add(item, x, y, z, w, h, d) Adding items to the world.
World:remove(item) Removing items from the world.
World:translate(item, x2, y2, z2, w2, h2, d2) Changing the position and dimensions of items in the world.
World:move(item, goalX, goalY, goalZ[, filter]) Moving an item in the world, with collision resolution.
World:moveRelative(item, dx, dy, dz[, filter]) Same as World:move() but uses a difference vector instead of goal position.
World:check(item, goalX, goalY, goalZ[, filter]) Checking for collisions without moving.
World:queryPoint(x, y, z[, filter]) Returns the items that touch a given point.
World:queryCube(x, y, z, w, h, d[, filter]) Returns the items that touch a given cube.
World:querySegment(x1, y1, z1, x2, y2, z2[, filter]) Returns the items that touch a segment.
World:querySegmentWithCoords(x1, y1, z1, x2, y2, z2[, filter]) An extended version of World:querySegment() which returns the collision points of the segment with the items, in addition to the items.
World:addResponse(name, response) Extends the default list of available filter() function responses.

Tables

CollisionInfo The info contained on every collision item.


Functions

Methods
World:init([cellsize=64])
World initialization.

Parameters:

  • cellsize number Size of the cell in pixels for spatial hashing. (default 64)
World:added(obj[, kwargs])
Component was added to Entity event. Adds "world" key to the Entity.C table.

Parameters:

  • obj l2df.class.entity Entity's instance.
  • kwargs table Keyword arguments.
    • lights {l2df.manager.render.Light,...} Array of lights used for drop shadows. Empty by default. (optional)
    • borders {x1=number,x2=number,y1=number,y2=number,z1=number,z2=number} Borders of the world. It's a global BBox restricting area of entities movement (if they use PhysixManager:move()). (optional)
    • layer string Layer for drawing. Careful: if setted it will change entity's layer. (optional)
    • depth number Depth of the world in px. Used for spatial hashing. (optional)
    • width number Width of the world in px. Used for spatial hashing. (default 0)
    • height number Height of the world in px. Used for spatial hashing. (default 0)
    • gravity number Gravity acceleration used in the world. (default 0)
    • friction number Friction used in the world. Value is bounded at [0; 1] segment. (default 0)
    • zoom number Default game's zoom. Used by Camera. (default 1)
    • inactive boolean If true the world would not receive update events. (default false)
World:removed(obj)
Component was removed from Entity event. Removes "world" key from Entity.C table.

Parameters:

World.getFromContext()
Static function for getting current world in stack. Should be called during "pre-update", "update" or "post-update" events only.

Returns:

    l2df.class.component.physix.world World component wrapped with its parent entity.
World:update(obj, dt, islast)
Component post-update event handler.

Parameters:

  • obj l2df.class.entity Entity's instance.
  • dt number Delta-time since last game tick.
  • islast boolean Processes only the last drawn frame.
World:liftdown(obj)
Component liftdown event handler.

Parameters:

World:liftup(obj)
Component liftup event handler.

Parameters:

World:add(item, x, y, z, w, h, d)
Adding items to the world. Throws error if an item already exists.

Parameters:

  • item mixed New item being inserted and linked with the provided BBox. Usually it is a table but also can be an object of any lua type except of userdata. When world is added as a component item might be an instance of the Entity class.
  • x number BBox X position.
  • y number BBox Y position.
  • z number BBox Z position.
  • w number BBox width.
  • h number BBox height.
  • d number BBox depth.

Returns:

    mixed An added item.
World:remove(item)
Removing items from the world.

Parameters:

  • item mixed Must be something previously inserted in the world with World:add. If this is not the case, function will raise an error. When world is added as a component item might be an instance of the Entity class.
World:translate(item, x2, y2, z2, w2, h2, d2)
Changing the position and dimensions of items in the world. Even if your "player" has attributes like player.x, player.y, and player.z, changing those will not automatically change them inside world. translate is one of the ways to do so: it changes the cube representing item inside world. This method always changes the cube associated to item, ignoring all collisions (use World:move() for that). It returns nothing.

Parameters:

  • item mixed Must be something previously inserted in the world with World:add. If this is not the case, function will raise an error. When world is added as a component item might be an instance of the Entity class.
  • x2 number New BBox X position.
  • y2 number New BBox Y position.
  • z2 number New BBox Z position.
  • w2 number New BBox width.
  • h2 number New BBox height.
  • d2 number New BBox depth.
World:move(item, goalX, goalY, goalZ[, filter])
Moving an item in the world, with collision resolution. goalX, goalY, goalZ are the desired x, y, and z coordinates. The item will end up in those coordinates if it doesn't collide with anything. If, however, it collides with 1 or more other items, it can end up in a different set of coordinates.

Parameters:

  • item mixed Must be something previously inserted in the world with World:add. If this is not the case, function will raise an error. When world is added as a component item might be an instance of the Entity class.
  • goalX number The desired X coordinate.
  • goalY number The desired Y coordinate.
  • goalZ number The desired Z coordinate.
  • filter function If provided, it must have this signature: local type = filter(item, other). type is a value which defines how item collides with other. If type is false or nil, item will ignore other completely (there will be no collision). If type is "touch", "cross", "slide" or "bounce", item will respond to the collisions in different ways. By default, filter always returns "slide". (optional)

Returns:

  1. number Actual X position where the object ended up after colliding with other objects in the world.
  2. number Actual Y position where the object ended up after colliding with other objects in the world.
  3. number Actual Z position where the object ended up after colliding with other objects in the world.
  4. {l2df.class.component.physix.world.CollisionInfo,...} Array of all the collisions that were detected.
  5. number The amount of collisions produced.
World:moveRelative(item, dx, dy, dz[, filter])
Same as World:move() but uses a difference vector instead of goal position.

Parameters:

  • item mixed Must be something previously inserted in the world with World:add. If this is not the case, function will raise an error. When world is added as a component item might be an instance of the Entity class.
  • dx number Difference between current item's X coordinate and its goal X position.
  • dy number Difference between current item's Y coordinate and its goal Y position.
  • dz number Difference between current item's Z coordinate and its goal Z position.
  • filter function Filter function. For more info see World:move(). (optional)

Returns:

  1. number Difference between actual X position where the object ended up and item's X position before movement.
  2. number Difference between actual Y position where the object ended up and item's Y position before movement.
  3. number Difference between actual Z position where the object ended up and item's Z position before movement.
  4. {l2df.class.component.physix.world.CollisionInfo,...} Array of all the collisions that were detected.
  5. number The amount of collisions produced.
World:check(item, goalX, goalY, goalZ[, filter])
Checking for collisions without moving.

Parameters:

  • item mixed Must be something previously inserted in the world with World:add. If this is not the case, function will raise an error. When world is added as a component item might be an instance of the Entity class.
  • goalX number The desired X coordinate.
  • goalY number The desired Y coordinate.
  • goalZ number The desired Z coordinate.
  • filter function Filter function. For more info see World:move(). (optional)

Returns:

  1. number Actual X position where the object ended up after colliding with other objects in the world.
  2. number Actual Y position where the object ended up after colliding with other objects in the world.
  3. number Actual Z position where the object ended up after colliding with other objects in the world.
  4. {l2df.class.component.physix.world.CollisionInfo,...} Array of all the collisions that were detected.
  5. number The amount of collisions produced.
World:queryPoint(x, y, z[, filter])
Returns the items that touch a given point. It is useful for things like clicking with the mouse and getting the items affected.

Parameters:

  • x number X coordinate of the point that is being checked.
  • y number Y coordinate of the point that is being checked.
  • z number Z coordinate of the point that is being checked.
  • filter function Function which takes one parameter (an item). queryPoint will not return the items that return false or nil on filter(item). By default, all items touched by the point are returned. (optional)

Returns:

  1. {mixed,...} List of the items from the ones inserted on the world (like player) that contain the point x, y, z. If no items touch the point, then items will be an empty table. If not empty, then the order of these items is random.
  2. number Length of the items list. It is equivalent to #items, but it's slightly faster to use instead.
World:queryCube(x, y, z, w, h, d[, filter])
Returns the items that touch a given cube. Useful for things like selecting what to display on the screen or selecting a group of units with the mouse in a strategy game.

Parameters:

  • x number BBox X position.
  • y number BBox Y position.
  • z number BBox Z position.
  • w number BBox width.
  • h number BBox height.
  • d number BBox depth.
  • filter function When provided, it is used to "filter out" which items are returned. If filter(item) returns false or nil, that item is ignored. By default, all items are included. (optional)

Returns:

  1. {mixed,...} List of items, like in World:queryPoint().
  2. number Equivalent to #items
World:querySegment(x1, y1, z1, x2, y2, z2[, filter])
Returns the items that touch a segment. It's useful for things like line-of-sight or modelling bullets or lasers.

Parameters:

  • x1 number X coordinate of the segment's start.
  • y1 number Y coordinate of the segment's start.
  • z1 number Z coordinate of the segment's start.
  • x2 number X coordinate of the segment's end.
  • y2 number Y coordinate of the segment's end.
  • z2 number Z coordinate of the segment's end.
  • filter function When provided, it is used to "filter out" which items are returned. If filter(item) returns false or nil, that item is ignored. By default, all items are included. (optional)

Returns:

  1. {mixed,...} List of items, like in World:queryPoint(), but sorted by proximity (from the closest to x1, y1, z1 to the farest).
  2. number Equivalent to #items.
World:querySegmentWithCoords(x1, y1, z1, x2, y2, z2[, filter])
An extended version of World:querySegment() which returns the collision points of the segment with the items, in addition to the items.

Parameters:

  • x1 number X coordinate of the segment's start.
  • y1 number Y coordinate of the segment's start.
  • z1 number Z coordinate of the segment's start.
  • x2 number X coordinate of the segment's end.
  • y2 number Y coordinate of the segment's end.
  • z2 number Z coordinate of the segment's end.
  • filter function When provided, it is used to "filter out" which items are returned. If filter(item) returns false or nil, that item is ignored. By default, all items are included. (optional)

Returns:

  1. {table,...} List of tables. Each element in the table has the following elements: item, x1, y1, z1, x2, y2, z2, t0 and t1.
  2. number Equivalent to #itemInfo.
World:addResponse(name, response)
Extends the default list of available filter() function responses. Further explanation would be written in near future.

Parameters:

  • name string Response name to be used as filter's return value.
  • response function Callback function calculating resulting movement position for that specific response.

Tables

CollisionInfo
The info contained on every collision item. Most of this info is useful only if you are doing semi-advanced stuff with collisions, but they could have some uses.

Fields:

  • item mixed The item being moved / checked.
  • other mixed An item colliding with the item being moved.
  • type string The result of filter(other). It's usually "touch", "cross", "slide" or "bounce".
  • overlaps boolean True if item "was overlapping" other when the collision started. False if it didn't but "tunneled" through other.
  • ti number Number between 0 and 1. How far along the movement to the goal did the collision occur.
  • move {x=number,y=number,z=number} The difference between the original coordinates and the actual ones.
  • normal {x=number,y=number,z=number} The collision normal; usually -1, 0, or 1 in x, y, and z.
  • touch {x=number,y=number,z=number} The coordinates where item started touching other.
  • itemCube {x=number,y=number,z=number,w=number,h=number,d=number} The cube item occupied when the touch happened.
  • otherCube {x=number,y=number,z=number,w=number,h=number,d=number} The cube other occupied when the touch happened.