Using objects in Rooms and Portals

VisualInstances) are treated in the same way by the engine. The portal renderer is slightly different, in that it makes a distinction between the different roles objects will have in your game. It makes this distinction to define the Rooms, and to render and process everything in the most efficient way.

Portal mode

CullInstance, where you can set a PortalMode. This determines how objects will behave in the portal system.

STATIC

STATIC. Static objects are objects within rooms that will not move throughout the lifecycle of the level. Things like floors, walls, ceilings are good candidates for STATIC objects.

DYNAMIC

they must not move outside of their original room. These objects are handled very efficiently by the system. Examples might include moving platforms, and elevators.

ROAMING

STATIC or DYNAMIC modes, because the system has to keep track of which room a roaming object is within.

GLOBAL

GLOBAL mode.

IGNORE

-bound) get converted to ignore portal mode automatically. They don’t need to show up during the game, but are kept in the scene tree in case you need to convert the level multiple times (e.g. in the Editor). You might also choose to use this for objects that you only want to show up in the editor (when RoomManager is inactive).

Should you place objects within rooms (in the scene tree) or not?

STATIC and DYNAMIC objects are ideally placed within rooms in the scene tree. The system needs to know which room they are in during conversion as it assumes they will never change room. Placing them within rooms in the scene tree allows you to explicitly tell the system where you want them.

Autoplace

STATIC and DYNAMIC objects outside the rooms in the scene tree, but within the RoomList branch. The system will attempt to autoplace the objects into the appropriate room. This works in most cases but if in doubt, use the explicit approach. The explicit approach is especially needed when dealing with internal rooms, which have some restrictions for sprawling objects. STATIC and DYNAMIC objects outside of rooms, they will not contribute to the room bound. If you are using the room geometry to derive the bound, tables and chairs can be placed outside the room. However, walls and floors should be explicitly within the Room’s branch of the scene tree to ensure the bound is correct. ROAMING and GLOBAL objects are recommended to be kept in a branch of the scene tree outside of any rooms or the RoomList. They can be placed inside the rooms, but to save confusion, they are normally better kept on their own branch. There are no restrictions on the placement of IGNORE objects.

Object Lifetimes

STATIC and DYNAMIC objects is tied to the lifetime of the level, between when you call rooms_convert() to activate the portal system, and calling rooms_clear() to unload the system. This is because quite a bit of pre-processing goes on during the conversion phase in order to render them efficiently. STATIC or DYNAMIC objects while the portal system is active. Doing so will cause the system to automatically unload because it is in an invalid state. You can however, freely show() and hide() these objects. The sequence should be therefore:

  • Load your level.
  • STATIC or DYNAMIC objects.
  • rooms_convert() after all the STATIC and DYNAMIC objects were added to the scene tree. ROAMING, GLOBAL or IGNORE can be freely created and deleted as required.

    Sprawling

    sprawling. This means that if the corner of an object extends into a neighbouring room, but the object’s main room is not showing (e.g. a train where the end is in a different room), the object will not be culled, and will still be shown. The object will only be culled if it is not present in any of the rooms that are visible.

    Portal Margins

    margin over which an object can cross without being considered in the next room. The margin is shown in the editor gizmo as a red translucent area. You can set the margin globally in the RoomManager. You can also override this margin value in any portal if you need to finetune things. As you edit the margin values in the inspector, you should see the margins update in the 3D editor viewport.

    Include in Bound

    Cull Instance > Include In Bound. While sprawling works great for large moving objects, it also gives you a lot more leeway in level design. You can for instance create a large terrain section and have it present in multiple rooms, without having to split up the mesh.

    Lighting

    DirectionalLights. DirectionalLights have no source room as they affect everywhere. They should therefore not be placed in a room. As DirectionalLights can be expensive, it is a good idea to turn them off when inside, see the later RoomGroups section for details on how to do this. Congratulations! You have now mastered the intermediate techniques required to use rooms and portals. You can use these to make games already, but there are many more features.