Constructor
new World(optionsopt)
Parameters:
Name | Type | Attributes | Description | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
options |
object |
<optional> |
Properties
|
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, |
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 |
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. |