Advanced Features

Most of the time, Poseidon is “add component, move object, magic happens.” But there’s a lot of power hiding in the inspector’s Advanced tab (and a few things that only exist in code). This page covers the features you reach for when your levels get more ambitious.

Facing: Inward vs Outward

Every Poseidon has a Facing, and it changes what the mesh means:

• Inward: the mesh represents empty space: a room, a tunnel, a cave. The walls face toward you when you’re standing inside it. This is the classic Poseidon carver.
• Outward: the mesh represents a filled thing: a mountain, a building, a chunk of terrain. A normal, everyday mesh, with faces pointing out.

The two interact the way you’d hope: push an inward tunnel into an outward mountain, and you get a tunnel through the mountain. The tunnel only exists where the mountain exists. Push two inward rooms together and they merge into one connected space. Outward objects take precedence over inward objects on the same layer, which is what clips that tunnel to the mountain’s bounds.

If your source mesh points the wrong way for the job (say, you want to use Unity’s default cube as a room), Flip All Faces in the Advanced tab flips every normal during generation. It works, but a properly authored mesh is always the better answer. Flipping the default cube is exactly what it’s there for, and not much more.

Layers (Layered Mode)

Layers answer the question: “how do I put a carve inside a carve?”

Without layers, every Poseidon in a scene is fair game to intersect with every other Poseidon. But say you’re building a big open cave (inward), and you want to place a small building (outward) inside that cave, and then carve rooms (inward) into that building. If everything lived in one soup, the building’s rooms would also try to carve the cave, and everything would fight.

The Layer number (Advanced tab) stacks these worlds. The mental model is nesting dolls:

• Layer 0, Outward: the world itself: terrain, mountains.
• Layer 0, Inward: spaces carved out of it: caves, tunnels, rooms.
• Layer 1, Outward: solid objects placed inside those spaces: a building in the cave, a pillar in the room.
• Layer 1, Inward: spaces carved into those: rooms inside the building.
• …and so on, as deep as your level design demands.

Each Poseidon only carves against its own layer’s peers and the layers immediately adjacent to it in this stack. An inward room on layer 1 doesn’t know or care about the cave on layer 0. That’s what keeps a “prefab building full of rooms” from carving into the world around it.

Check out Example Scene 6 (Layered Mode) to see this in action.

Protrude Mode

Normally, an inward carver exists within its context: a tunnel carved into a mountain only exists where the mountain exists. Poke the tunnel out the side of the mountain and the overhanging part disappears; it’s been clipped to its parent.

Protrude Mode (Advanced tab) opts an object out of that clipping. A protruding tunnel still carves the mountain, but is not carved by it. It “exists in the void,” poking out the side if that’s where you put it. This only makes sense in scenes mixing inward and outward objects, usually complicated scenarios involving 3+ objects with different facings. Use it with caution, and only when the default clipping is visibly not what you want.

Carving Groups

Layers stack carves vertically — worlds nested inside worlds. Carving Groups split the scene horizontally: islands of Poseidons that carve each other but ignore everything else.

Add a Poseidon Carving Group component to any GameObject, and every Poseidon underneath it only carves other Poseidons in the same group. Everything without a group above it lives in the implicit global group. A group only ever narrows what carves: members still have to overlap, be enabled, and share a scene — all the usual rules — they just also have to share the group.

A few rules that fall out of “it works the way you’d hope”:

• Nearest group wins. Groups nest. A Poseidon belongs to the closest enabled group above it (a group on the Poseidon’s own GameObject counts).
• Grouped and ungrouped never mix. A grouped Poseidon won’t carve a global one, even if they overlap. Dropping a group onto existing geometry fences it off from the world around it.
• The checkbox is the island’s switch. Disable the component and it becomes transparent: its descendants fall up to the next group above (or the global group) and, at editor time, recarve into their new surroundings automatically. Re-enable it and the island seals itself off again.

Group References

Sometimes one logical island is physically scattered across the hierarchy — a prefab here, a set piece there. Poseidon Carving Group Reference points at a group defined elsewhere; think of it as the asmref to the group’s asmdef. Descendants of the reference belong to the target’s group exactly as if they sat under it.

A reference has no identity of its own. If its target is missing or disabled — or the reference itself is disabled — it’s simply transparent, and its descendants resolve as if it weren’t there. That also means disabling the definition group switches off the entire distributed island everywhere at once. (And no, a reference can’t point at another reference: the field only accepts real groups, so there are no chains to untangle.)

Groups at Runtime

At editor time, group changes recarve automatically like everything else. At runtime, Poseidon’s standing rule applies: nothing recarves unless you ask (see Runtime Carving). Toggling a group, retargeting a reference, or streaming a whole level section in and out costs nothing by itself — membership is simply re-read whenever a Poseidon is next marked dirty.

When you do want an island toggle to take effect immediately, that’s one call:

islandGroup.enabled = false;   // merge the island back into the world…
islandGroup.RecarveMembers();  // …and apply it now

RecarveMembers() dirties every active Poseidon under the component and queues an async recarve; former neighbors heal and new neighbors carve in, exactly as if everything had moved. Poseidons recarved this way receive UpdateReason.GroupChanged in their OnCarveFinished callback, so gameplay code can tell an island toggle from ordinary collateral.

Priority

When two surfaces end up exactly coplanar (imagine two rooms whose floors sit at precisely the same height, carving into each other), someone has to win, or the textures z-fight. Priority (Advanced tab) is the tie-breaker: the object with the higher priority gets its texture shown on the shared surface.

Boundary Handling: Split vs Preserve

By default (Split), Poseidon does textbook CSG at intersection boundaries: triangles that cross the boundary are sliced precisely along it. Exact cuts, more triangles.

Preserve takes the opposite trade: original triangles are kept whole, and only the triangles that are entirely inside the other mesh are removed. No new geometry is ever created; the triangle count can only go down.

The cut is obviously rougher, so why would you want that? Because for some jobs the precise boundary never mattered:

• Hull generation: smashing kitbashed rocks/cliffs together into one shell and throwing away the buried geometry.
• Kitbashing outward-facing objects: where the intersection line is hidden inside the overlap anyway.

If you’re kitbashing outward geometry and your triangle counts are exploding, try Preserve.

Strategy: Auto, Brutus, Octresius

The Advanced tab also lets you pick the carving algorithm per object:

• Brutus: brute force: check every triangle against every triangle. Very fast on small meshes, tedious on big ones.
• Octresius: builds an octree first to prune which triangles could possibly intersect. Much faster for complex geometry, but pays an up-front construction cost. Octresius is also not as memory efficient if you’re using it at Runtime. Essentially: great if you have a complicated mesh, but will be slower because of the cost on small meshes.
• Auto (default): Poseidon picks for you based on how much geometry is involved. Leave it here unless you have a reason not to. Once you pass a certain threshold of triangles, we automatically switch to Octresius in order to speed it up.

Smallest Triangle Area

An escape hatch: if a particular carve is producing degenerate micro-triangles that cause trouble downstream, set Smallest Triangle Area to a very small positive number and any generated triangle smaller than that gets removed during cleanup. The default of -1 skips the process entirely. (If your actual goal is cleaner meshes rather than removing broken ones, you want Mesh Cleanup instead.)

Hooks: Extending Poseidon from Code

PoseidonHooks lets external code plug into the carving process without touching Poseidon internals. Handy for tool integrations.

Skipping objects conditionally

Register a predicate that can suppress carving per-GameObject. Return a reason string to skip (it shows in the inspector as “Temporarily Inactive: {reason}”), or null to let the object carve:

// e.g. from an [InitializeOnLoad] editor class, or runtime startup code
PoseidonHooks.RegisterSkipPredicate(go =>
    go.CompareTag("UnderConstruction") ? "still being placed by MyLevelTool" : null);

Consuming finalized meshes

OnMeshFinalized fires whenever a Poseidon commits a new mesh to its GameObject, after the carve is fully assembled and ready:

PoseidonHooks.OnMeshFinalized += (poseidon, mesh) =>
{
    // e.g. push the carved mesh onto a NavMesh source, a custom collider, an exporter...
};

There’s also a per-object callback if you only care about one Poseidon: every Poseidon exposes OnCarveFinished, which delivers the UpdateReason flags explaining why it recarved (moved? neighbor changed? manually dirtied?).

This is incredibly useful if you’re working with external systems that need the mesh but don’t need work with Unity’s MeshFilter directly. A good example would be using your own physics engine within Unity or an external one like Quantum.

Integrations

Poseidon ships with a couple of lightly-maintained bridges to other tools, each off by default behind a scripting define. Each one’s whole job is to hand Poseidon’s mesh to the other tool at the right moment — whether that’s stepping out of the way so you can edit, or forwarding the carved result to a collider — nothing more.

UModeler

UModelerBridge detects when you start actively editing a Poseidon-carved object inside UModeler, hands it Poseidon’s BaseMesh instead of the carved output so you’re editing clean base geometry, and re-syncs BaseMesh + triggers a recarve once you exit UModeler’s edit mode.

Enable it with the POSEIDON_UMODELER_INTEGRATION scripting define. It works by reflecting into UModeler’s internals (there’s no public API for this), so it can break silently if a UModeler update renames the fields it looks for. Treat it as best-effort, not a guarantee.

Photon Quantum

QuantumBridge listens for OnMeshFinalized and pushes each freshly carved mesh onto the object’s QuantumStaticMeshCollider3D, so Quantum’s deterministic physics collides against the carved geometry instead of the original base mesh.

Enable it with the POSEIDON_QUANTUM_INTEGRATION scripting define. It’s deliberately tiny — a hook subscription and a couple of lines — so treat it as a worked example as much as a feature: if you’re on a different physics engine (or your own), copy it and swap QuantumStaticMeshCollider3D for your collider type.

Scripting Defines Reference

A few behaviors are controlled by Scripting Define Symbols (Project Settings → Player → Scripting Define Symbols):