World

World

Main handler for an entity world. The World keeps track of managers and systems,
and also provides methods to create, select and remove entities.
Note that process() has to be called manually if objects need to be added and retrieved within the same update loop.

Constructor

new World(optionsopt)

Parameters:
Name Type Attributes Description
options object <optional>
Properties
Name Type Attributes Default Description
sumerianRunner SumerianRunner <optional>
tpfSmoothingCount boolean <optional>
10

Specifies the amount of previous frames to use when computing the 'time per frame'

Members

(static) STATE_PAUSED

Value returned by World#state when the world is paused. Use
World#resume to resume the world's execution or World#stop
to stop the world's execution.

World#time and World@fixedTpfTime are not updated while
the world is paused.

Most systems are not executed while in this state. See the documentation
for each system to determine how it behaves when the world is paused.

(static) STATE_RUNNING

Value returned by World#state when the world is running. Use
World#pause to pause the world's execution or World#stop
to stop the world's execution.

All systems execute while the world is in this state.

World#time and World@fixedTpfTime are updated only while
the world is running.

Note that the world will execute only when the engine execution loop is
running, as controlled by SumerianRunner#startEngine, and {@link
SumerianRunner#stopEngine}.

(static) STATE_STOPPED

Value returned by World#state when the world is stopped. Use {@link
World#start} to begin executing the world.

World#time and World@fixedTpfTime are not updated while
the world is stopped.

Most systems are not executed while in this state. See the documentation
for each system to determine how it behaves when the world is stopped.

(static) useSystemTimingMarks

User Timing Marks for Sumerian Systems help analyze where processing time is used. Enable it
by setting the document cookie 'sumerianProfiling' = 'useSystemTimingMarks'

_addedEntities :Array.<Entity>

Stores added entities of which systems need to be notified.

_changedEntities :Array.<{entity:Entity, component:Component}>

Stores added entity components of which systems need to be notified.

_state :number

The current world execution state. Should be one of the World.STATE_XXX
values.

by

Entity selector. Its methods return an EntitySelection. Can select by system, component, attribute or tag. See examples for usage.

Will get additional methods when an EntityManager is attached.

Example
var bySystem = sumerianRunner.world.by.system("RenderSystem").toArray();
var byComponent = sumerianRunner.world.by.component("cameraComponent").toArray();
var byTag = sumerianRunner.world.by.tag("monster").toArray()
var byAttribute = sumerianRunner.world.by.attribute("hit-points").toArray();

entityManager :EntityManager

Main keeper of entities.

fixedTpf :number

The fixed time step to use for physics and other fixed-updates.

fixedTpfTime :number

Current fixed step accumulated time.

interpolationTime :number

Interpolation alpha time value: a number between 0 and 1. Use to interpolate between two fixed updates from the frame update.

isPaused

True if the world state is World.STATE_PAUSED.

isRunning :number

True if the world state is World.STATE_RUNNING.

isStarted

True if the world state is World.STATE_RUNNING or
World.STATE_PAUSED.

maxSubSteps :number

Max fixed steps to use for the fixed update loop.

publicWorld

Gets the public api World object for this internal api World object.

smoothedTpf :number

The tpf, averaged by a number of samples.

state :number

Get the current world execution state. The value will be One of {@link
World.STATE_STOPPED}, World.STATE_RUNNING, or {@link
World.STATE_PAUSED}.

sumerianRunner :SumerianRunner

SumerianRunner for updating the world and calling the renderers.

systems :Array.<System>

An array of the world's System objects in priority order.

time :number

Accumulated time per frames(tpf) the world has been running. Calculated at the start of each frame.

tpf :number

Time since last frame in seconds.

tpfSmoothingCount :number

Number of samples to use for smoothing the tpf.

Methods

(static) forPublicWorld(publicWorld) → {World}

Gets the internal api World object for a specified public api World object.

Parameters:
Name Type Description
publicWorld PublicWorld

The public api World object.

add(…args) → {World}

Universal shorthand for adding managers, systems, and entities.

Parameters:
Name Type Attributes Description
args Entity | Manager | System <repeatable>

The entities, managers,
and/or systems to add.

Example
// Add two entities and register a component, all in one swoop
var entity1 = new Entity(sumerianRunner.world, 'Entity 1');
var entity2 = new Entity(sumerianRunner.world, 'Entity 2');
sumerianRunner.world.add(entity1, entity2);

addedComponent(entity, component)

Let the world and its systems know that a component has been added to an entity.

Parameters:
Name Type Description
entity Entity

The entity to which the component has been added.

component Component

The component that has been added.

addEntity(entity, recursiveopt) → {World}

Add an Entity to the world.

Parameters:
Name Type Attributes Default Description
entity Entity

Entity to add.

recursive boolean <optional>
true

If entity hierarchy should be added recursively.

clear()

Clears the World and all the sytems associated with it. Once this method
is called this instanceof of World is unusable.

clearSystem(type) → {World}

Removes the System of type 'type'.

Parameters:
Name Type Description
type string

Type of system to remove.

createEntity(…args) → {Entity}

Creates a new Entity with an optional MeshData, MeshRenderer, Camera, Script and Light component, placed optionally at a location. Parameters can be given in any order.

Parameters:
Name Type Attributes Description
args * <repeatable>

Values used to initialize the entity. Any string argument
is used as the entity's name. Other arguments are used to create components
on the entity by calling Entity#setComponent.

Example
// Create a sphere entity and add it to the world
var sphereEntity = world.createEntity(new Sphere(32, 32), material, [0, 0, 5]).addToWorld();
// Create a camera entity and add it to the world
var cameraEntity = world.createEntity(new Camera(), [0, 0, 3]).lookAt(new Vector3(0, 0, 0)).addToWorld();

createOcclussionTree()

Setups the Occlusion Graph to a tree with a root node of the given size.

fixedUpdate()

Do a fixed time update of all systems.

getEntities() → {Array.<Entity>}

Get an array of all entities in world.

getManager(type) → {Manager}

Retrieves a Manager of a certain type.

Parameters:
Name Type Description
type string

Type of manager to retrieve eg. 'EntityManager'.

getOcclusionTree() → {Array.<BoundingBox>}

Returns all the active tree nodes' bounds.

getSystem(type) → {System}

Retrieve a System of type 'type'.

Parameters:
Name Type Description
type string

Type of system to retrieve.

pause()

Sets the world's execution state to World.STATE_PAUSED.

System#pause will be called for all of the world's systems.

Throws:

if the current world state is not {@link
World.STATE_RUNNING}.

Type
Error

process()

Process all added/changed/removed entities and callback to active systems and managers. Usually called automatically each frame.
Has to be called between adding an entity to the world and getting it back.

processEntityChanges()

Notify systems of newly added entities and components. We delay notifying
systems of adds until the next update so that the system sees the entity
after it is fully initialized. We notify of removes immediately, before
the remove actually happens, so that the system can see the entity before
the change is made.

registerComponent(componentConstructor) → {World}

Registers a component type. This is necessary to allow automatic creation of components
from 'basic' data types (CameraComponents from Cameras, MeshRendererComponents from materials and so on).
When a SumerianRunner is created, it registers TransformComponent, MeshDataComponent,
MeshRendererComponent, CameraComponent, LightComponent and ScriptComponent automatically.

Parameters:
Name Type Description
componentConstructor Component
Example
// Register the animation component type so that animations
// can be automatically created.
sumerianRunner.world.registerComponent(AnimationComponent);

removedComponent(entity, component)

Let the world and its systems know that a component has been removed from an entity.

Parameters:
Name Type Description
entity Entity

The entity from which the component has been added.

component Component

The component that has been removed.

removeEntity(entity, recursiveopt) → {World}

Remove an Entity from the world.

Parameters:
Name Type Attributes Default Description
entity Entity

Entity to remove.

recursive boolean <optional>
true

If entity hierarchy should be removed recursively.

resume()

Sets the world's execution state to World.STATE_RUNNING.

System#resume will be called for all of the world's systems.

Throws:

if the current world state is not {@link
World.STATE_PAUSED}.

Type
Error

setManager(manager) → {World}

Adds a Manager to the world.

Parameters:
Name Type Description
manager Manager

setSystem(system) → {World}

Adds a System to the world.

Parameters:
Name Type Description
system System
Throws:

Error if the world is not currently stopped.

start()

Sets the world's execution state to World.STATE_RUNNING.

System#start will be called for all of the world's systems.

Throws:

if the current world state is not {@link
World.STATE_STOPPED}.

Type
Error

stop()

Sets the world's execution state to World.STATE_STOPPED.

System#stop will be called for all of the world's systems.

World#time and World@fixedTpfTime will be set to 0.

update(tpf) → {World}

Update the world. This will run process and fixedUpdate.

Parameters:
Name Type Description
tpf number

Time since last called, in seconds.