Guild of Writers

About

SubWorlds are objects that make your avatar move in the direction that they move. They are used to simulate relativity and momentum in Uru. Some prime examples are the Er'Cana harvester and the Gahreesen spinning buildings.

Use

To use SubWorlds in PyPrp you need a few things; a entrance-region, a exit-region, the SubWorld itself, and (if you don't want to fall though the floor) some objects that you can interact with while you are in the SubWorld eg. an elevator floor.

Note: Both of the next two regions need to have "Bounds" set.

The entrance-region should be placed where you want to enter the SubWorld, say the inside-threshold of the elevator and should carry this AlcScript:

<object>:
    type: region
    regiontype: subworld
    region:
        subworld: <subworld-object name>

The exit-region should be on the outer-threshhold of your elevator (if you have an elevator) and should have the AlcScript:

<object>:
    type: region
    regiontype: subworld
    physical:
        subworld: <subworld-object name>

Alternatively, your exit region can encompass the walkable area of the subworld, and have a slightly different script:

<object>:
    type: region
    regiontype: subworld
    region:
        onexit: 1
    physical:
        subworld: <subworld-object name>

The onexit parameter indicates that the region should be triggered when the avatar leaves it. This way, whenever you step off your subworld platform, you will be returned to the normal world.

The SubWorld should be an empty representing the coordinate system of the subworld, and it's script should look like this:

<object>:
    type: subworld

Here's the most important part; The SubWorld colliders:

For anything you're going to collide against in the non-SubWorld you have as a collider... right? For everything you're going collide with in the SubWorld you need a collider with this AlcScript:

<object>:
   physical:
       subworld: <subworld-object name>

This is why the exit-region needed to have the physical.subworld code attached, it's because regions are a kind of collider, and if you can't collide, you can't trigger it. You should also set this for all regions that are expected to be triggered while you are in the SubWorld eg. elevator click-regions.

That just about wraps up everything you need to know. :)

Proper setup of Actors

To be able to walk on a floor or platform in a moving SubWorld (in other words, to "interact with a platform"), it's necessary to set the Actor flag in Blender (under Logic) for this platform object.
But to get this Actor exported correctly, some rules should be mentioned:

1. Keep object scaling to 1.0

Objects which need the "Actor" flag set in Blender, MUST NOT have any object scaling applied. Object scaling must always be 1.0 for X,Y and Z (Transform Properties windows, N-key).
If you need to scale such an Actor, it must be done in Edit Mode. Otherwise the Actor object will appear in URU in the wrong location, and with a wrong scaling.
(Having a rotation applied to the object is okay though.)

2. Always use volumes for the floor

Simple "planes", or other flat meshes which don't have volume, do not work well as a floor to walk onto in a SubWorld; they appear in URU at a slightly shifted location. Closed meshes (volumes), like a cube, work much better, because the location in URU will then be the same as seen in Blender (as long as the object has no scaling, see 1.).
If you already have such a simple plane, extruding it to a volume helps.

And additionally (although this has not a direct relation to subworlds or actors, but because mostly objects are parented to a moving SubWorld):

3. Don't modify child objects

Never modify an object which is parented (attached as a child to a parent). Do all scaling, modeling, moving first, and finally do the parenting, if needed.
If the objects needs modifications later, un-parent it, modify, and parent again. Otherwise the object's origin in URU might differ from the origin you see in Blender, which causes it to appear somewhere else in the game.

Non-horizontal SubWorld regions

In some cases, you might want to use SubWorlds which are not horizontally aligned, e.g. when you want to play with gravitation in an unusual direction.
Then you should take care about how your regions are constructed.

4. Don't run into regions with your head first

Regions which detect the entering and leaving of a SubWorld, should be constructed in a way that the avatar never touches the next event-triggering plane of the region with his head first!
Best practice is to let the avatar touch the region at 90 degrees, if applicable; if this cannot be achieved, the first contact with the region should be the avatar's feet.

This image should explain how this is meant:

This image is an example of a bad setup (avoid this):

Explanation: In the 2nd image, the avatar gets rotated back to vertical when he leaves the subworld on the left side - which immediately puts him back in again because this makes him touch the enter region (the avatar gets rotated around the feet as origin); this lets him rotate to 30 degree again (aligned to subworld), which pushes him out again...
just constructing the borders as described above avoids these effects.

The Avatar's Bounding Box

If you're wondering why region boundaries do not trigger exactly where you expect them to do - this is because triggering does not occur at the avatar's center point.
Instead, the avatar has an invisible box surrounding him, which does the collision detection. (At least understand this as a concept to understand how it virtually works.)

This "box" is not actually a rectangular one, but behaves as if it has an elliptical shape, like this:

So, if you're facing a region boundary, triggering does occur at about 3.0/2 = 1.5 units before the avatar's center reaches the region.

Now have fun playing with SubWorlds.