Portals

public static partial class Portals

Lookup for portals (docs/portals.md D1): the Portal components on this process, on a client what the network gateway has told it about the portals near it, and the link poses between scopes (Map, Turn). What a client draws and how each drawn scope stands is in the other half of this class (PoseOf, RenderMatrixOf, RenderingLayerOf).

Properties

All

public static IReadOnlyList<Portal> All { get; }

Every enabled portal component on this process.

ProxyLayer

public static int ProxyLayer { get; }

The physics layer a portal's proxies and aperture colliders are on (NebulaConfig.PortalProxyLayer, 31 unless the process was configured otherwise). A game keeps it free of its own objects and out of its own layer masks (docs/portals.md D26).

Known

public static IReadOnlyDictionary<ulong, PortalRecord> Known { get; }

On a client: the portals the network gateway has told it about, by derived id. A portal is sent behind the container row of either of its faces and withdrawn with the row (docs/portals.md D45).

KnownLinks

public static IReadOnlyDictionary<ulong, PortalLinkRecord> KnownLinks { get; }

On a client: the state of each link the network gateway has told it about, by link id. A link is sent to the clients that hold the container row of either face, with whether this client is a member and whether it may look through.

Anchor

public static ulong Anchor { get; }

On a client: the scope the drawing is measured against, the anchor (docs/portals.md D40): the scope whose frame the local view's frame resolves to, which is the world the player first walked in from. Nothing of it is ever moved to draw.

DrawnScopeIds

public static IReadOnlyList<ulong> DrawnScopeIds { get; }

On a client: the scopes drawn right now, the view first (docs/portals.md D40): the pawn's scope, every scope one open link away that the client may look through, the public world (0) and the scopes with an InstanceScenes.KeepDrawn request. Content of a scope the client looks through is shown without a KeepDrawn request.

Events

Crossed

public static event Action<NetworkIdentity, ulong, ulong, ulong> Crossed;

Raised on this process when an entity crossed between two scopes through a portal: on a worker for every committed member, on a client when the entity's container change arrived and was carried through the link. Portal.Crossed says the same for one portal, where its component is known to the process (a client may not have loaded the content a portal stands in). Arguments: the entity, the portal's derived id (0 when only an instance's pose related the scopes), the scope it left and the scope it entered.

KnownChanged

public static event Action KnownChanged;

Raised on a client when a portal record or a link record arrived or was withdrawn.

SlotChanged

public static event Action<ulong, uint> SlotChanged;

Raised on a client when a scope gained a rendering-layer slot (arguments: the scope and its single layer bit) or lost it (the bit is 0), after Nebula restamped its renderers. A game re-aims its lights' rendering-layer masks here.

Methods

Find

public static Portal Find(ulong portalId);

The enabled portal component with this derived id (Portal.PortalId), or null.

FindLink

public static PortalLink FindLink(ulong linkId);

The live link with this id (PortalLink.Id) of any enabled portal on this process, or null.

Map

public static PortalPose Map(ulong from, ulong to, PortalPose pose);
public static Double3 Map(ulong from, ulong to, Double3 position);

A pose of scope from in scope to, carried through the link between them (docs/portals.md D39): the position about the faces and in double, the rotation turned. Scopes that no portal and no instance pose relates, and a scope with itself, return the pose unchanged. For an instance a template portal built this is its pose against its host (InstancePoses), which every process learns from lease rows; for a portal with a fixed far side it is the portal's two faces, known to a worker for the links it holds and to a client from the portal records it was sent. Where several portals join the same two scopes, the one whose face is nearest the pose is used.

TryMap

public static bool TryMap(ulong from, ulong to, PortalPose pose, out PortalPose mapped);

As Map, but says whether anything relates the scopes: false (and mapped the pose unchanged) when no portal and no instance pose does. A scope with itself is related by the identity. For a game that must tell "the same place on the other side" from "no way through" before it carries a pose, a direction or a hold across.

Turn

public static Quaternion Turn(ulong from, ulong to);

What turns a rotation or direction of scope from's axes into scope to's, for an entity crossing between them through a portal: the identity unless the link between them is turned. A game keeping its own heading or velocity bookkeeping (a pawn's yaw) applies it in a Portal.Crossed handler. It replaces InstancePoses.Turn for anything that crosses a portal, and answers for a portal with a fixed far side too.

PoseOf

public static ScopePose PoseOf(ulong scope);

A drawn scope's pose against the Anchor, composed in double through the link poses along the portals from the anchor (docs/portals.md D40, ScopePose). The identity for the anchor and for a scope nothing relates to it. This is where the scope is drawn: simulation, prediction and every pose a game reads stay in the scope's own upright space. While cameras draw, Nebula has posed the scope's root containers by it (and the cameras by the view's, when the view is not the anchor).

RenderMatrixOf

public static Matrix4x4 RenderMatrixOf(ulong scope);

A matrix that takes a point of scope's own upright space, in drawing space, to where it is drawn (docs/portals.md D41). For what a transform cannot carry: meshes a game draws itself with matrices it keeps (Graphics.RenderMeshInstanced, a scatter, a decal batch). Multiply the matrix you would draw an unposed instance with by this one (RenderMatrixOf(scope) * instanceMatrix), while SceneRenderOrigin.Drawing runs: "drawing space" is a scene position minus SceneRenderOrigin.Offset, which is what the roots Nebula posed are in. A matrix built from a transform read inside Drawing already includes the pose and must not be multiplied again. The identity for the anchor and for a scope nothing relates to it.

DrawWith

public static void DrawWith(Transform transform, ulong scope);

Draw transform as part of scope: while cameras draw, Nebula poses it by the scope's PoseOf as it poses the scope's root containers, and puts it back afterwards. For what a game keeps outside every container but places in a scope's own space: a light that follows the local player's head, an effect between a hand and what it holds. Without it such a thing is drawn unposed, away from the scope it belongs to, whenever that scope is not the Anchor. Pass 0 to stop. A transform already under something posed is left to it; a destroyed one is forgotten.

KeepUnposed

public static void KeepUnposed(Camera camera, bool keep = true);

Keep camera where the game put it while Nebula draws (keep false puts it back with the rest). When the view is not the Anchor, Nebula moves every camera that draws by the view's pose; a camera that looks at something of its own rather than the world (a portrait of the player's avatar in a corner of space, a preview rendered to a texture) would be moved off it.

RenderingLayerOf

public static uint RenderingLayerOf(ulong scope);

The rendering-layer bit (a single bit of NebulaConfig.ScopeRenderingLayers) a drawn scope holds, or 0 when slots are off, the scope is not drawn, or more scopes are drawn than there are bits (docs/portals.md D42). Nebula stamps this bit, and only this bit of the reserved mask, on its static content, its chunks' content and its entities' renderers; use it in a light's rendering-layer mask and a portal's masks.

StampRenderingLayer

public static void StampRenderingLayer(Transform root, ulong scope);

Stamp the scope's rendering-layer bit on every renderer under root: for content a game adds to a scope after Nebula stamped it (a prop built under a chunk's content root later, a renderer added to an entity). Does nothing when slots are off. Nothing outside the reserved bits changes.