World - Documentation

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

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 systems 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.