InstanceScenes

public static class InstanceScenes

Loads instance geometry into separate physics scenes. Query an entity's PhysicsScene for gameplay collision tests. Creating the geometry is asynchronous in play mode (Prepare, ContentState).

Methods

PhysicsFor

public static PhysicsScene PhysicsFor(ulong instanceId);

The physics scene for a loaded scope. An unknown private scope returns an invalid scene.

Prepare

public static bool Prepare(Container container);

Start creating this container's geometry. Returns false when its resource is missing or contains network identities, or when an earlier attempt failed.

True means the content exists or is on its way, not that it has finished loading. In play mode the scope's physics scene is created and the container moved into it at once (a quick step, done while a portal prepares and not while an entity crosses), but the prefab is loaded and instantiated asynchronously, one step each time ContentState is asked, so a large interior never costs a tick its budget (docs/portals.md §14, item 3). A missing resource is then discovered when the load finishes, and ContentState reports InstanceContentState.Failed. Content with an IInstanceContentLoader may still be building after that; ContentState reports that too. Outside play mode the content is not created at all, and the resource is checked at once.

Complete

public static bool Complete(Container container);

Finish creating this container's content now, blocking if it has to: the guarantee an entity moved into an instance has always had, that the geometry it stands on exists. A portal never needs it, because its far side is ready before it opens (docs/portals.md D10); this is the fallback for a placement that was not prepared for (a restored entity, a transfer into a container nobody warmed). Returns false when the content cannot be created.

ContentState

public static InstanceContentState ContentState(Container container);

Whether a prepared container's content has finished loading: InstanceContentState.Failed when any IInstanceContentLoader under it has failed, InstanceContentState.Loading while any is still loading, and InstanceContentState.Ready otherwise. Content with no loaders, a container in the public world, and a container that has not been prepared are InstanceContentState.Ready. A child or carried container reports the content that Prepare loads for it.

ContentProgress

public static float ContentProgress(Container container);

How far a prepared container's content has loaded, from 0 to 1: the mean of its loaders' IInstanceContentLoader.Progress, counting a ready loader as 1. It is 1 when the content has no loaders. Use it for a loading indicator; ContentState decides readiness.

KeepDrawn

public static void KeepDrawn(ulong instanceId);

Keep a scope's content drawn on this client while the local pawn is in another scope: the static content Prepare loads for its instance parts, and the content under the World.ChunkContext.Root of its scoped grid's chunks. A client normally draws only the pawn's own scope and the public world, and keeps other resident scopes hidden; use this to show the other side of an open doorway. Content created or loaded while the request is live starts drawn.

Requests are counted: match each call with one StopKeepingDrawn. The scope is hidden again only when its last request is withdrawn. Nebula turns on only the renderers it turned off itself, so renderers the game turned off stay off. A request outlives the scope's content: when the content is released Nebula forgets its renderers but keeps the request, so content of the scope prepared again starts drawn.

Rendering only. It loads nothing, and changes no physics scene, interest, ownership or message: content that is not resident on this client stays absent. A worker records the request and ignores it. The public world (instanceId 0) is always drawn, so a request for it does nothing.

StopKeepingDrawn

public static bool StopKeepingDrawn(ulong instanceId);

Withdraw one KeepDrawn request for a scope. When it was the last one and the local pawn is in another scope, the scope's content is hidden again. Returns false, and changes nothing, when the scope has no request.

IsDrawn

public static bool IsDrawn(ulong instanceId);

Whether a scope's content is drawn on this client: true for the public world, for the local pawn's scope, and for a scope with a live KeepDrawn request; false for any other scope. Always true on a process that is not a client, which hides nothing.