World

local World = require('encompass').World
local world = World:new()

A World is the glue that holds all the Engines, Entities, and Components together.

The World’s update function drives the simulation and can be controlled from your engine’s update loop.

It is a mistake to instantiate elements of encompass directly except for World. These elements should be created either through appropriate World functions, or by Engines.

It is not a good idea to add Engines to the world at runtime. Set Engines up at initialization time.

Function Reference

World:new()
Returns:An instance of World.
World:create_entity()
Returns:An instantiated Entity.
World:create_message(message_type, ...)
Arguments:
  • message_type (prototype) – A Message prototype.
  • ... – Alternating key and value arguments. The values should have types appropriate to their matching keys as defined by the Message prototype. If these do not match the Message prototype, an error will be thrown.
Returns:

An instantiated Message of the given prototype.

Example:

world:create_message(MyShipSpawnMessage,
    'x_position', 640,
    'y_position', 360,
    'x_velocity', 0,
    'y_velocity', 0
)
World:add_detector(detector_type)
Arguments:
  • detector_type (prototype) – A Detecter prototype.
Returns:

An instantiated Detecter of the given prototype.
World:add_spawner(spawner_type, args)
Arguments:
  • spawner_type (prototype) – A Spawner prototype
  • args (table) – Arguments that will be passed to the Spawner initialize callback.
Returns:

An instantiated Spawner of the given prototype.
World:add_modifier(modifier_type, args)
Arguments:
  • modifier_type (prototype) – a Modifier prototype.
  • args (table) – Arguments that will be passed to the Modifier initailize callback.
Returns:

An instantiated Modifier of the given prototype.
World:add_renderer(renderer_type)
Arguments:
  • renderer_type (prototype) – a Renderer prototype.
Returns:

An instantiated Renderer of the given prototype.
World:destroy_all_entities()

Destroys all entities that currently exist in the world. Useful for situations where you may want to clear the world to reset it without needing to re-initialize engines.

World:update(dt)
Arguments:
  • dt (number) – Delta time.

Updates the simulation based on given delta time, advancing the simulation by one frame.

The actions performed in a frame update are as follows:

  • Activates/Deactivates marked Entities
  • Updates Detectors
  • Registers Messages with appropriate Spawners
  • Updates Spawners
  • Updates Modifiers
  • Destroys marked Entities
  • Recalculates draw order of components if any changed

Example:

function love.update(dt)
    world:update(dt)
end
World:draw(canvas)
Arguments:
  • canvas (Canvas) – A reference to a Canvas that all Renderers will be given.

Draws to the given Canvas based on the composition of all Renderers in the simulation.

If you’re not using LOVE, this could be your engine’s concept of a Framebuffer or anything you can send draw calls to.

Example:

function love.draw()
    love.graphics.setCanvas(world_canvas)
    love.graphics.clear()
    love.graphics.setCanvas()
    love.graphics.clear()

    world:draw(world_canvas)

    love.graphics.setCanvas()
    love.graphics.setBlendMode('alpha', 'premultiplied')
    love.graphics.setColor(1, 1, 1, 1)
    love.graphics.draw(world_canvas)
end