Sleep API

Updated for v0.4.0

Conceptual

Entities in nengi are checked for changes every frame on the server, and any changes they experience are sent to any client within view. This makes for a very powerful programming paradigm -- a game developer can simply add entities to an instance and rapidly create a multiplayer experience.

However the automagic networked behavior of an entity is performance intensive, and games with high player counts will find that they are limited to 50-500 entities. When trying to optimize a game it becomes neccesary to audit whether any given networked feature was truly best represented as a nengi entity. Is the object controlled by the player and experiencing very frequently changes? It should be an entity. Is the object just an indestructible rock that exists on the map? That shouldn't be an entity, it should just be part of the map and downloaded as a file or sent onConnect in a message.

The development time it takes to make any complex feature out of message is often much greater than the time it takes to make the same feature as an entity. That said, many features simply cannot be made as entities such as tilemaps or chat systems, and the performance of messages is very good.

The sleep api exists as a performance enhancement which seeks to allow a broader use of entities.

API at a glance

instance.sleep(entity)
instance.wake(entity)
instance.wakeOnce(entity)
instance.isAsleep(entity)
instance.isAwake(entity)

An entity that is sleeping will not be checked for changes each frame. This enhancement allows for potentially hundreds and sometimes thousands of entities to be present in an instance. A sleeping entity retains the functionality of being sent to a player who approaches the entity, and being culled from the view as the player moves far away from the entity. This means that entities can be created/destroyed while in the sleep state and players wil see them disappear and disappear. This means that some types of objects should *always* be represented as a sleeping entity, such as:

Note: these are also fine to network as messages instead of entities, but if they are entities, make them sleep. Entities do not need to be woken to be destroyed, they only need to be woken to have their properties updated to the clients.

wakeOnce

The wakeOnce function will wake an entity for one frame, meaning that any changes it has experienced will be sent to those who can see it. An optimal example of this would be a tree that has hitpoints. For the majority of the tree's existence it remained a static object until a player came along and dealt damage. If in the same code that deals damage to the tree we invoke instance.wakeOnce(tree) then we'll see the tree's hitpoints drop.