Portals - update docs for 3.4 beta 3 (#5154)

Co-authored-by: Hugo Locurcio <[email protected]>

tutorials/3d/portals/advanced_room_and_portal_usage.rst

@@ -17,7 +17,7 @@ This works because if a monster is in an area that is completely out of view for
 How does a monster know whether it is within the gameplay area?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This problem is solved because the portal system contains a subsystem called the **Gameplay Monitor** that can be turned on and off from the :ref:`RoomManager<class_RoomManager>`. When switched on, any roaming objects that move inside or outside the gameplay area (whether by moving themselves, or the player moving) will receive callbacks to let them know of this change.
+This problem is solved because the portal system contains a subsystem called the **Gameplay Monitor** that can be turned on and off from the :ref:`RoomManager<class_RoomManager>`. When switched on, any roaming objects that move inside or outside the gameplay area (whether by moving themselves, or the camera moving) will receive callbacks to let them know of this change.
 
 You can choose to either receive these callbacks as ``signals``, or as ``notifications``.
 
@@ -104,3 +104,30 @@ The tent is a simple room inside a terrain room (which contains the ground, the
 This is perfect for improving performance in open world games. Often your buildings can be scenes (including the rooms and portals) that can be reused. When viewed from the outside, interiors will mostly be culled, and when viewing from the inside other buildings and most of the outside will be culled. The same goes for other players and objects that are inside and outside the buildings.
 
 *Scene is 'Diorama Eco scene' by Odo, with slight changes for illustration purposes.* `CC Attribution <https://creativecommons.org/licenses/by/4.0/>`_
+
+Internal room scenes
+^^^^^^^^^^^^^^^^^^^^
+
+Let us look in detail at another practical example for an open world. We want to place houses (as internal rooms) on an island, but have each house as a self-contained scene containing both the interior *and* the external mesh of the house.
+
+.. image:: img/house_scene.png
+
+We have created a Room node (which will become the internal room) into which we have placed the interior meshes. We have also created a Portal with no links (so autolinking will be used). The exterior mesh is *not* within the room. It will be autoplaced, and we are intending for it to be placed within the outer room.
+
+However there is a problem. The naive autoplace algorithm will look at the center of the exterior mesh, and attempt to place it *within* the internal room. We want to avoid this somehow, as the idea of the exterior mesh is to have something rendered from the outside, so it must be in the outer room for everything to work.
+
+To get around this problem, there is a special setting to enable you to express a preference for autoplacing in an outer room. Each object has an **Autoplace Priority** setting. When set to ``0``, there is no preference (the object will be placed in the highest priority room).
+
+However, if we set this autoplace priority to ``-1`` for example, the autoplace will always choose a ``-1`` priority room (if one is present at that location). So if we set the outer room priority to ``-1``, it will always place our exterior into our "outside" room.
+
+.. image:: img/autoplace_priority.png
+
+This gives us a helpful extra bit of control for these kinds of situations, and makes the entire system much more flexible.
+
+.. note:: As the default autoplace priority is ``0``, you can't effectively force objects into RoomGroups with priority ``0``. However there are plenty of priority values available so this should not be a problem in practice.
+
+The final scene looks something like this, with houses instanced wherever you want them on a giant outer room.
+
+.. image:: img/island.png
+
+The house exteriors will be placed in the outer room, and therefore can always be seen when looking from the outside. The interiors will only be rendered when a view into the entry portals is visible.

tutorials/3d/portals/editing_rooms_and_portals.rst

@@ -21,19 +21,55 @@ Putting all the ideas together, here is an example scene tree:
 Creating room systems in Blender (or other modeling tools)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Although you can create your room system entirely within the editor, you can also build rooms and portals within your modeling tool. There is one small snag - modeling tools such as Blender have no knowledge of Room, RoomGroup and Portal nodes. In order to work around this we use the naming conventions that were discussed earlier.
+Although you can create your room system entirely within the editor, you can also build rooms and portals within your modeling tool. There is one small snag - modeling tools such as Blender have no knowledge of Room, RoomGroup and Portal nodes. In order to work around this we use a series of naming conventions. The first time Godot encounters these specially named nodes, it will convert them into Rooms, RoomGroups and Portals.
 
-Rooms should be created as Empty objects with names such as ``Room_kitchen`` (substituting your preferred room name). If you place meshes within the rooms within the modeling tool, these Empties will form Spatial nodes in Godot, and will be converted to room nodes automatically during the room conversion phase.
+Postfix convention
+^^^^^^^^^^^^^^^^^^
 
-Creating a RoomGroup is done by creating an Empty object with the name prefix ``RoomGroup``. For instance, you can create an Empty object called ``RoomGroup_house`` and it will be converted to a RoomGroup.
+- ``-room`` becomes a :ref:`Room<class_Room>`.
+- ``-roomgroup`` becomes a :ref:`RoomGroup<class_RoomGroup>`.
+- ``-portal`` becomes a :ref:`Portal<class_Portal>`.
+- ``-bound`` becomes a manual bound.
 
-Creating Portals in modeling tools
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Rooms and RoomGroups should be created as Empties within Blender. Any mesh children of the ``-room`` Empty will thus be placed in the Room during conversion in Godot.
 
-Portals also use the same naming convention as within Godot - the name should start with the prefix ``Portal_`` followed by the name of the room the portal should link to. However, for portals, we want to specify the shape and position of the polygon within the modeling tool, so the nodes should be Meshes rather than Empties.
+For example:
+
+- ``kitchen-room`` - create a Room called "kitchen".
+- ``outside-roomgroup`` - create a RoomGroup called "outside".
+- ``kitchen-portal`` - create a Portal leading to the "kitchen" Room.
+
+Portals
+^^^^^^^
+
+Portals are different from Rooms. In Portals, we need to specify the geometry of the Portal in our modelling tool, in addition to just the name. To do this your "portal-to-be" should be created as a Mesh.
 
 Portal meshes have some restrictions to work properly. They must be convex, and the polygon points should be in the same plane. The accuracy to the plane does not have to be exact, as Godot will automatically average the direction of the portal plane. Once converted to a :ref:`Portal<class_Portal>` node, the snapping to the portal plane is enforced, and the vertices are specified (and editable) as 2D coordinates in the inspector, rather than 3D points.
 
+The portal's naming is quite important. You can either name the portal ``-portal`` which will attempt to autolink the Portal in Godot, or you can use the name of the Room you wish to link the Portal to as a prefix.
+
+Wildcard
+^^^^^^^^
+
+In most cases, this can be done using a name such as ``kitchen-portal``. However, there is one problem. Blender and Godot do not deal well when you have multiple objects with the same name. What happens when we want more than one Portal to lead to the kitchen?
+
+The workaround is the use of a *wildcard* character, ``*``. When Godot reads the wildcard, it will ignore anything placed after it in the name.
+
+This means we can use the following portal names:
+
+- ``kitchen*1-portal`` - creates a Portal leading to the "kitchen".
+- ``kitchen*2-portal`` - also creates a Portal leading to the "kitchen".
+- ``kitchen*anything_you_want_here-portal`` - also works.
+
+Wildcards work on all of the nodes which use these naming conventions.
+
+Manual bounds
+^^^^^^^^^^^^^
+
+Manual bounds are a way of explicitly setting the convex hull for a room, and are used if they are present as children of a room in the scene tree. Aside from the postfix, the naming is unimportant. They should be meshes (i.e. MeshInstance in Godot). Bear in mind they will be converted to convex hulls during the conversion process, so they don't have to be perfect.
+
+.. tip:: Once used during conversion, they will be converted to the ``IGNORE`` **Portal Mode** and won't be shown. You can alternatively use **Generate Points** within the editor to convert these to a set of points stored in the room, and delete the original ``-bound`` MeshInstance.
+
 Portal point editing
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -41,18 +77,20 @@ Portals are defined by a combination of the transform of the portal node, and by
 
 The default portal has 4 corners as shown in the inspector:
 
-.. image:: img/portal_points.png
+.. image:: img/portal_point_editing.png
+
+You can edit these points in the gizmo or inspector to make a better match to the opening in your game level. It's generally better to keep the number of points as low as possible for the efficiency of the system. For example, it's better to risk rendering a little too much than to spend the time culling objects at 20 different edges.
 
-You can edit these points in the inspector to make a better match to the opening in your game level. But bear in mind it generally better to keep the number of points as low as possible for the efficiency of the system. It is better to risk rendering a little too much than to spend the time culling objects at 20 different edges, for example.
+.. _doc_room_point_editing:
 
 Room point editing
 ~~~~~~~~~~~~~~~~~~
 
-You also have the option to manually edit the points used to define the convex hull of a room. These points are not present by default, you would typically create them by pressing the **Generate Points** button in the editor toolbar, when a room is selected. This will transfer the auto bound from the geometry (or manual ``Bound_`` mesh) into the inspector. Once there are points in the inspector, they will be used and override any other method. So if you wish to revert your manual editing, simply delete all the points.
+You also have the option to manually edit the points used to define the convex hull of a room. These points are not present by default. You would typically create them by pressing the **Generate Points** button in the editor toolbar when a room is selected. This will transfer the auto bound from the geometry (or manual ``-bound`` mesh) into the inspector. Once there are points in the inspector, they will be used and override any other method. So if you wish to revert your manual editing, delete all the room's points.
 
-.. image:: img/room_points.png
+.. image:: img/room_point_editing.png
 
-Manually editing rooms' points is more difficult than editing portal points, but it can be useful in some situations, especially where the auto-bound doesn't *quite* get the right result you want. It is usually a good idea to use a lot of **Simplification** in the inspector for the Room before generating the points. Be aware though that by default, the **Simplification** value will be inherited from the RoomManager.
+Manually editing points can be useful in some situations, especially where the auto-bound doesn't *quite* get the right result you want. It is usually a good idea to use a lot of **Simplification** in the inspector for the Room before generating the points. Be aware though that by default, the **Simplification** value will be inherited from the RoomManager.
 
 RoomManager
 ~~~~~~~~~~~
@@ -60,7 +98,7 @@ RoomManager
 Show Debug
 ^^^^^^^^^^
 
-This can be used to turn on and off display of portals in the editor, and control the amount of logging. Debug will always be set to ``false`` on exported projects.
+This can be used to control the amount of logging, especially the room conversion logs. Debug will always be set to ``false`` on exported projects.
 
 Debug Sprawl
 ^^^^^^^^^^^^
@@ -75,7 +113,7 @@ To keep drawcalls to a minimum, the system offers the option to automatically me
 Plane Simplification
 ^^^^^^^^^^^^^^^^^^^^
 
-In some cases, automatically generated convex hull bounds may contain a very large number of planes. This is not ideal because it slows down determining which room a camera or object is within. The system can optionally simplify hulls. The degree of simplification can be selected by the user, between ``0`` (no simplification) and ``1`` (maximum simplification). You can also override this value in individual rooms.
+In some cases, the convex hulls automatically generated for rooms may contain a very large number of planes, particularly if you use curved surfaces. This is not ideal because it slows down the system. This option can optionally simplify hulls. The degree of simplification can be selected by the user, between ``0`` (no simplification) and ``1`` (maximum simplification). You can also override this value in individual rooms.
 
 Portals
 ~~~~~~~
@@ -83,12 +121,12 @@ Portals
 Portal Active
 ^^^^^^^^^^^^^
 
-Portals can be turned on and off at runtime. This is especially useful if you have open and closing doors.
+Portals can be turned on and off at runtime. This is especially useful if you have doors that can open and close.
 
 Two Way
 ^^^^^^^
 
-Portals can either be two way or one way. One way portals may be useful for example to create windows that can be seen out of, but not seen into. This can help performance when viewing buildings from outdoors.
+Portals can either be two-way or one-way. The default two-way portals are quicker to set up in most circumstances, but one-way portals can be useful in some cases. For example, you can use one-way portals to create windows that can be seen out of, but not seen into. This can help performance when viewing buildings from outdoors.
 
 Particle Systems
 ~~~~~~~~~~~~~~~~

tutorials/3d/portals/first_steps_with_rooms_and_portals.rst

@@ -9,14 +9,31 @@ Anytime you want to use the portal system, you need to include a special node in
 Room Conversion
 ^^^^^^^^^^^^^^^
 
-This conversion must take place every time you want to activate the system, it does not store the *room graph* in your project (for flexibility and to save memory). You can either trigger it by pressing the **Convert Rooms** button in the editor toolbar when the RoomManager is selected, or you can call the ``rooms_convert()`` method in the RoomManager. This latter method will be what you use in-game. Note that for safety, best practice is to call ``rooms_clear()`` before unloading / changing levels.
+This conversion must take place every time you want to activate the system. It does not store the *room graph* in your project (for flexibility and to save memory). You can either trigger it by pressing the **Convert Rooms** button in the editor toolbar (which also has a keyboard shortcut), or you can call the ``rooms_convert()`` method in the RoomManager. This latter method will be what you use in-game. Note that for safety, best practice is to call ``rooms_clear()`` before unloading or changing levels.
 
-If you convert the level while the editor is running, the portal culling system will take over from the normal Godot frustum culling. This may affect some editor features. For this reason, you can turn the portal culling on and off, using the **Active** setting in the RoomManager node.
+.. image:: img/convert_rooms_button.png
+
+If you convert the level while the editor is running, the portal culling system will take over from the normal Godot frustum culling. This may affect some editor features. For this reason, you can turn the portal culling on and off, using either the **View Portal Culling** toggle in the **View** menu on the editor toolbar (which also has a keyboard shortcut), or via the **Active** setting in the RoomManager node.
 
 .. note:: To use the RoomManager, you have to tell it where the rooms are in your scene tree, or rather where the RoomList node is. This RoomList is the parent of your rooms - see below. If the RoomList is not set, conversion will fail, and you will see a warning dialog box.
 
 .. image:: img/room_manager.png
 
+The RoomList
+^^^^^^^^^^^^
+
+Before we create any rooms, we must first create a node to be the parent of all the static objects, rooms, roomgroups and so on in our level. This node is referred to as the the ``RoomList``.
+
+.. image:: img/roomlist_node.png
+
+.. note:: The roomlist is **not** a special node type, it can just be a regular Spatial.
+
+You will need to assign the roomlist node in the RoomManager, so the RoomManager knows where to find the rooms.
+
+Why do we use a specific branch of the scene tree, and not use the scene root? The answer is that there are many internal details of the system which are easier to manage if the rooms are placed on their own branch.
+
+Often, you will end up completely replacing the roomlist branch at runtime in your game as you load and unload levels.
+
 Rooms
 ~~~~~
 
@@ -52,12 +69,7 @@ There is one exception however for :ref:`internal rooms<doc_rooms_and_portals_in
 How do I create a room?
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-A :ref:`Room<class_Room>` is a node type that can be added to the scene tree like any other. You can place objects within the room by making them children and grand-children of the Room node. Instead of placing the rooms as children of a scene root node, you will need to create a Spatial especially for the job of being the parent of all the rooms. This node we will refer to as the ``RoomList``. You will need to assign the roomlist node in the RoomManager, so the RoomManager knows where to find the rooms.
-
-Room naming convention
-^^^^^^^^^^^^^^^^^^^^^^
-
-Unlike most nodes in Godot, a specific naming convention should be followed in order to identify each room. The name should have the prefix ``Room_`` followed by the name you wish to give the room, e.g. ``Room_kitchen``, ``Room_lounge``. If you don't follow these naming guidelines, the system will warn you and may not work correctly.
+A :ref:`Room<class_Room>` is a node type that can be added to the scene tree like any other. You can place objects within the room by making them children and grand-children of the Room node.
 
 How do I define the shape and position of my room convex hull?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -65,8 +77,8 @@ How do I define the shape and position of my room convex hull?
 Because defining the room bound is the most important aspect of the system, there are THREE methods available to define the shape of a room in Godot:
 
 1. Use the geometry of the objects contained within the room to automatically create an approximate bound.
-2. Provide a manual bound. This is a MeshInstance in the room that has geometry in the shape of the desired bound, with a name prefixed by ``Bound_``. This is something you might choose to do if you create your levels in Blender or similar (see :ref:`doc_rooms_and_portals_blender`).
-3. By manually editing the points that define the convex hull, in the room inspector.
+2. By manually editing the points that define the convex hull, in the room inspector, or dragging the points using the editor gizmo (see :ref:`doc_room_point_editing`).
+3. Provide a manual bound. This is a MeshInstance in the room that has geometry in the shape of the desired bound, with a name with a postfix ``-bound``. This is something you might choose to do if you create your levels in Blender or similar (see :ref:`doc_rooms_and_portals_blender`).
 
 While the first option can be all that is required, particularly with simple rooms, or for pre-production, the power of the manual bounds gives you ultimate control (at the expense of a small amount of editing). You can also combine the two approaches, perhaps using automatic bounds for most rooms but manually editing problem areas.
 
@@ -83,25 +95,23 @@ If you create some rooms, place objects within them, then convert the level in t
 
 :ref:`Portal<class_Portal>`\ s are special convex polygons. You position over the openings between rooms, in order to allow the system to see between them. You can create a portal node directly in the editor. The default portal has 4 points and behaves much like a ``plane`` :ref:`MeshInstance<class_MeshInstance>`. You can add or remove points using the inspector. A portal will require at least 3 points to work - this is because it needs to form a polygon rather than a point or line.
 
-Portals only need to be placed in one of each pair of neighbouring rooms (the *"source room"*). The system will automatically make them two way unless you choose otherwise in the portal node's properties. The portal normal should face *outward* from the source room. The front face should be visible from *outside* the room. The editor gizmo indicates the direction the portal is facing with an arrow, and a different color for each face.
+To save editing effort, **only one Portal is required between each pair of Rooms**. You *do not need* to (and indeed should not) create two Portals that overlap in opposite directions. Portals default to being two-way (but you can make them one-way in the Portal inspector).
 
-.. image:: img/portal_inspector.png
+You should therefore place a portal in only one of each pair of neighbouring rooms - this is the portal's *"source room"*. Generally it doesn't matter which you choose as the source room. The portal normal (the arrow in the gizmo) should face *outward* from the source room.
 
-Like rooms, portals also follow a naming convention which is as follows:
+.. image:: img/portal_inspector.png
 
-- Prefix ``Portal_``.
-- Optional : You can add a suffix of the room that the portal will lead to ('destination room'). E.g. ``Portal_kitchen``. This name is not just descriptive; it affects behavior when converting rooms (see below).
+Do not be confused by the arrow. Although the arrow shows which direction the portal faces, most portals will be *two-way*, and can be seen through from both directions. The arrow is more important for ensuring that the portal links to the correct neighbouring room.
 
-The suffix is optional. In many cases, the system can automatically detect the nearest room that you intended to link to and do this for you. It is usually only in problem areas you will need to use the suffix.
+Portal linking
+^^^^^^^^^^^^^^
 
-In rare cases, you may end up with two or more portals that you want to give the same name, because they lead into the same destination room. However, Godot does not allow duplicate names at the same level in the scene tree. The solution to this is the wildcard character ``*``. If you place a wildcard at the end of the name, the rest of the characters will be ignored. For example, ``Portal_Kitchen*1`` and ``Portal_Kitchen*2``.
+There are two options for dealing with specifying which room the portal should link to.
 
-All in all there are three ways of specifying which room a portal should link to:
-- Leaving the name suffix blank to use auto-linking.
-- Add suffix to the Portal node's name.
-- Assigning the **Linked Room** in the inspector for a Portal node. This is simply a shortcut for setting the name by renaming the node.
+- Leave the **Linked Room** in the inspector blank. The system will attempt to *autolink* the portal to the nearest neighbour room during conversion. This works fine in most cases.
+- You can explicitly specify the room by setting the **Linked Room** in the inspector.
 
-.. note:: Portals have some restrictions to work properly. They should be convex, and the polygon points should be in the same plane. The snapping of points to a plane is enforced because portal points are only defined in 2D (with X and Y coordinates). The node transform is used to convert these to world-space 3D points. The node transform thus determines the portal orientation.
+.. note:: Portals are defined as a set of 2D points. This ensures that the polygon formed is in a single plane. The transform determines the portal orientation. The points must also form a *convex* polygon. This is enforced by validating the points you specify, ignoring any that do not form a convex shape. This makes editing easier while making it difficult to break the system.
 
 Trying it out
 ~~~~~~~~~~~~~

tutorials/3d/portals/rooms_and_portals_example.rst

@@ -13,14 +13,14 @@ This tutorial will introduce you to building a "Hello World" room system with tw
 Step 1
 ~~~~~~
 
-.. image:: tutorial_simple/img/tutorial_simple1.png
+.. image:: tutorial_simple/img/tutorial_simple_1.png
 
 - Create a new project.
 - Add a :ref:`Spatial<class_Spatial>` as the scene root (on the screenshot, it's called "Root").
 - Next add a :ref:`RoomManager<class_RoomManager>` node. We will need this later to process the room system.
 - Next we need to start defining our rooms. We create all our rooms under another Spatial we have called 'RoomList'.
 - Add a new :ref:`Room<class_Room>` node as a child of the roomlist.
-- Give it a  name that starts with the prefix ``Room_``. We add our chosen name as a suffix. Here, we have used ``kitchen``.
+- We have named the room ``Kitchen``.
 - We will now create the geometry of our room. The names you give to the geometry is up to you.
 - Create a :ref:`MeshInstance<class_MeshInstance>` for the floor. Create a box by adding a CubeMesh resource to the MeshInstance. Scale and position it to form a floor.
 - Create MeshInstances for the walls. Create more box meshes for this, then scale and position them. Be sure to leave an opening on one side. You will need to create two wall segments to do this on that side.
@@ -28,27 +28,27 @@ Step 1
 Step 2
 ~~~~~~
 
-.. image:: tutorial_simple/img/tutorial_simple2.png
+.. image:: tutorial_simple/img/tutorial_simple_2.png
 
 - Now we need to create the other room.
-- You can do this simply by duplicating the first room (select the ``Room_kitchen`` node, right click and choose **Duplicate**).
+- You can do this simply by duplicating the first room (select the ``Kitchen`` node, right click and choose **Duplicate**).
 - Rotate and position the second room so that the openings line up.
-- Rename the second room to ``Room_lounge``.
+- Rename the second room to ``Lounge``.
 
 Step 3
 ~~~~~~
 
-.. image:: tutorial_simple/img/tutorial_simple3.png
+.. image:: tutorial_simple/img/tutorial_simple_3.png
 
 - Next, we will add a portal between the two rooms.
-- Create a new :ref:`Portal<class_Portal>` in the kitchen, and call it ``Portal_lounge``. The naming scheme tells the system which room it should link to.
+- Create a new :ref:`Portal<class_Portal>` in the kitchen.
 - Scale and position the portal using the node ``Transform`` in the inspector, so it fits within the opening between the two rooms.
 - The portal plane should face *outward* from the source room, i.e. towards the lounge. This direction is indicated by the arrow in the editor gizmo, and portal gizmo's color.
 
 Step 4
 ~~~~~~
 
-.. image:: tutorial_simple/img/tutorial_simple4.png
+.. image:: tutorial_simple/img/tutorial_simple_4.png
 
 - To make things more exciting, we want to add a few more boxes to the rooms.
 - Placing these boxes as children or grandchildren of the room nodes explicitly tells the system which room the objects should be in. However, we can also create these objects *outside* the rooms. Provided they are in the RoomList branch, the system will attempt to automatically place them in the correct room at runtime.
@@ -59,7 +59,7 @@ Step 4
 Step 5
 ~~~~~~
 
-.. image:: tutorial_simple/img/tutorial_simple5.png
+.. image:: tutorial_simple/img/tutorial_simple_5.png
 
 - Next comes a crucial stage. We must let the RoomManager know where the rooms are!
 - Select the RoomManager and look in the Inspector window in the **Paths** section.
@@ -68,7 +68,7 @@ Step 5
 Step 6
 ~~~~~~
 
-.. image:: tutorial_simple/img/tutorial_simple6.png
+.. image:: tutorial_simple/img/tutorial_simple_6.png
 
 - Make sure you have saved your project before this next step. It is always a good idea to save and make a backup before converting.
 - Select the RoomManager, and you will see a button in the toolbar at the top of the 3d editor viewport called **Convert Rooms**. Press this button.
@@ -89,4 +89,6 @@ Some things to try
 - The geometry you created so far is all ``STATIC`` (non-moving). If you look in the inspector for geometry nodes, you will see they derive from ``CullInstance``. Here you can set the **Portal Mode** for objects in the portal system. This determines how the node is processed.
 - If you now write a script to move one of your objects within a room and view it through a Camera as the scene runs, you may notice that the object gets culled incorrectly. This is because ``STATIC`` objects are assumed not to move in the system. If you instead change the object to ``DYNAMIC``, it should now update the culling correctly.
 - There are several ``portal_modes``, these are described in the main documentation.
-- Try turning the portal on and off at runtime from your script. You can call ``set_portal_active()`` to open and close the portal. 
+- Try turning the portal on and off at runtime from your script. You can call ``set_portal_active()`` to open and close the portal.
+- If you select the portal, you should see 4 handles appear. Try dragging the portal points with the mouse, and see how it affects the objects that are culled.
+- If you select a room and click the **Generate Points** button in the toolbar, it will store the points of the room hull in the room inspector. You can now edit these with the gizmo handles.

tutorials/3d/portals/using_objects_in_rooms_and_portals.rst

@@ -33,7 +33,7 @@ Global mode is for objects that you don't want occlusion culled at all. Things l
 IGNORE
 ^^^^^^
 
-Ignore is a special mode for objects that will be essentially free in the system. Manual bounds (``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).
+Ignore is a special mode for objects that will be essentially free in the system. Manual bounds (``-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?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -43,7 +43,7 @@ Should you place objects within rooms (in the scene tree) or not?
 Autoplace
 ^^^^^^^^^
 
-However, for ease of use, it is also possible to place ``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. This explicit approach is especially needed when dealing with internal rooms, which have some restrictions for sprawling objects.
+However, for ease of use, it is also possible to place ``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.
 
 .. image:: img/freeform.png
 
@@ -59,6 +59,7 @@ It is important to note that the lifetime of ``STATIC`` and ``DYNAMIC`` objects
 You should therefore not try to create or delete ``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.
 - Place any ``STATIC`` or ``DYNAMIC`` objects.
 - Then run ``rooms_convert()`` *after* all the ``STATIC`` and ``DYNAMIC`` objects were added to the scene tree.