Class: World

World is an organisational container for entities (generally of type Entity), and is the most important class in Ammo. It holds, organises and processes the batch of entities assigned to it. There can only be one active world at a time, so each one is separate from another.

You can use worlds to organise entities however you like, but they're most commonly used to separate distinct sections of a game. For example, you have one for the menu, and one for the actual game. Or, you might have one for each area or level in the game.

Most often, when you want a new type of world, you'll want to make a subclass of World, overriding and adding functionality as needed. You can then create an instance of it and assign it to `ammo.world to make it the active world.

Note that entities are not the only thing a world can contain. In reality, it can contain any table, which can support different functionality of the world as it chooses. For example, to make a table updatable all you need is an update method and a active property set to true. A good example of this is the Delay class from the tweens module. Therefore, when I refer to "entities," I'm also referring to all valid tables you can add to the world.

Layers

Everything in the world is drawn in layers, which have entities assigned to them. Layers are indexed by numbers, which can be both negative and positive, where the lower the number, the higher the entities in it are drawn. Layers can have a scale assigned to them; the camera will be applied with its coordinates multiplied by this scale. This allows you to create effects like parallax scrolling, where a scale of 1 is the playing field, scales less than 1 are background layers, and scales greater than 1 are foreground layers.

Layers have two optional callbacks you can use, one for before the layer is drawn, and one for after. These callbacks are referred to as "pre" and "post", respectively. You could use this to apply a shader to a particular layer, for example.

You can create layers in a couple of ways, one is to use World:addLayer or World:setupLayers. You can also just set the layer property in an entity; if the layer doesn't exist when the entity is added, it will be created, though you won't be able to set its scale and callbacks.

Properties

active
A boolean dictating whether or not this world should update.

all
All the entities this world is updating. Don't access this more than necessary, as it entails a call to LinkedList:getAll.

camera
The world's current camera. If set to nil, a blank camera will be created (via Camera:new()); this is the default setting.

count
The current number of entities contained within this world.

visible
A boolean dictating whether or not this world should draw.

Methods

initialize()
Initialises the world. When overriding this in your subclasses, you must call this using World.initialize(self).

add(...)
Marks one or more entities to be added to the world if they don't currently belong to another world. They will be added at the end of the frame.

...: One or more entities.

addLayer(index, scale, pre, post)
Creates a new layer in the world. Note that if a layer already exists at this index, this will overwrite it, therefore it's best to call this before any entities are added.

index: The index for this layer.
scale: The scale for this layer. Defaults to 1. pre: The pre callback. Defaults to nil.
post: The post callback. Defaults to nil.

addLayer(t)
Alternate form of addLayer, using a table to provide the arguments. For example:

self:addLayer{15, 1, pre = func1, post = func2}
self:addLayer{index = 16, scale = 2, post = func4}

index: t[1] or t.index.
scale: t[2] or t.scale.
pre: t.pre.
post: t.post.

draw()
The draw callback called by ammo.draw. This loops through all the layers calling draw on everything visible. If you override this, you must call it using World.draw(self).

iterate()
Returns the iterator for the LinkedList that contains all the entities in the world (by calling LinkedList:iterate).

remove(...)
Marks one or more entities for removal from the world, if of course they already belong to this world. They will be removed at the end of the frame.

...: One or more entities.

removeAll()
Removes all entities from the world.

setupLayers(t)
Allows you to add multiple layers in one call via a table. The key is the index, and value can be either a number or a table. If a number, it will denote the scale. If a table, it will be handled similarly to World:addLayer(t), expect the index is absent and the scale is t[1] instead of t[2].

An example:

self:setupLayers{
  [-1] = 2, -- sets the scale
  [0] = { 1, pre = someFunc, post = fooBar }, -- sets the pre and post callbacks
  [1] = 0.8,
  [3] = 0.6
}

See World:addLayer for more.

t: The table.

start()
Called when this world is made the current one. This does nothing by default, but can be overridden if needed.

stop()
Called when this world is no longer the current one. This does nothing by default, but can be overridden if needed.

update(dt)
The update callback called by ammo.update. It loops through all the entities, calling update on everything active. If you override this, you must call it using World.update(self, dt).

dt: Delta time.