Jovian Zone System v0.1.0

The Zone System lets you paint polygon regions on your map and assign encounter rules to each region. At runtime, you query a world position and get back a fully resolved ZoneContext with the encounter table, difficulty tier, and chance.

Key Features

• Three zone roles: Base, Modifier, and Override for layered encounter design
• Visual polygon editing: Drag vertices, insert on edges, delete vertices in the Scene view
• Concave polygon support: Ear-clipping triangulation renders any shape correctly
• Multi-plane support: XY, XZ, or YZ — one setting controls everything
• No physics dependency: Pure math ray-casting with AABB pre-rejection
• Save workflow: Create → Edit → Save with duplicate ID/name validation
• Role-based colors: Configured in settings, auto-applied on role change
• Zone duplication: Independent copies with unique IDs and assets
• JSON export: For runtime loading or external tools
• UPM package: Standard Unity Package Manager layout

1. Scene Setup

1. Create a GameObject and add the ZonesObjectHolder component.
2. Set the Map Plane field to match your map orientation.

2. Create Your First Zone

1. Open Window → Zone System → Zone Editor.
2. Click Create New Zone.
3. Enter a name, select a shape (Square, Circle, or Polygon).
4. Click Create & Edit.
5. Edit zone data fields (role, priority, encounter settings).
6. Click Save Zone to persist the asset.
7. Use Scene view handles to adjust the polygon shape.

The Zone Editor window (Window → Zone System → Zone Editor) is the primary tool for managing zones.

Zone List View

Shows all ZoneInstance objects in the current scene. Each row displays:

• Color swatch: Role-based color from editor settings
• Zone name and summary (role, priority, tier, chance)
• Select button: Opens the zone for editing
• Duplicate button (📋): Creates an independent copy with a new asset
• Delete button (✕): Removes the zone and its asset

Zones with missing ZoneData show a warning icon with options to add data or delete the zone.

Create Zone

Click Create New Zone to open the creation dropdown:

• Enter a Zone Name
• Select a Shape (Square, Circle, Polygon)
• Click Create & Edit

The zone is created in-memory and enters edit mode immediately. You must click Save to persist the asset.

Edit Mode

When editing a zone, all ZoneData fields are available inline:

• Identity: Zone ID, Zone Name, Role, Priority, Shape
• Role-specific fields: Shown/hidden based on the selected role
• Save Zone button: Validates and persists changes
• Delete Zone button: Removes the zone entirely

Save Validation

On save, the editor checks for:

• Duplicate Zone ID: No two assets may share the same zoneId
• Duplicate asset name: No two assets may have the same file name

If a conflict is found, an error is displayed and saving is blocked.

Auto-applied Changes on Save

• The GameObject name is updated to match the zone name
• The asset file is renamed to match the zone name
• If the shape type was changed, the polygon resets to the new default shape

Export Section

At the bottom of the editor window, expand Export Zones to JSON to export all scene zones to a JSON file for runtime loading.

When a zone is in edit mode, yellow handles appear in the Scene view for each polygon vertex.

Controls

Shapes

Additional Tools (Inspector)

• Center Transform: Moves the GameObject’s transform to the polygon’s centroid without changing the zone’s world position
• Reset Shape: Resets the polygon to the default for the current shape type
• Duplicate Zone: Creates an independent copy with its own ZoneData asset

Roles

Resolution Order

When querying a world position, the ZoneResolver follows this order:

1. If any Override zone is present → use the highest-priority Override exclusively
2. Find the highest-priority Base zone → encounter table + baseline difficulty
3. Stack all Modifier zones multiplicatively on top
4. Clamp and return a ZoneContext

Modifier Stacking

Modifiers are multiplicative, so each one is independent:

Base chance 0.30  x  Cursed Road 1.8  x  Night Modifier 1.2  =  0.648

Priority

Higher priority values take precedence. When multiple zones of the same role overlap, the highest-priority one wins (for Base and Override) or all are stacked (for Modifier).

Access via Window → Zone System → Settings. If no settings asset exists, one is created automatically.

Fields

Role Colors

Each ZoneRole has a configurable color in the settings. When you change a zone’s role in the editor, its debug color is automatically updated to match. Colors are used for:

• Scene view polygon fill and border
• Zone list row background tinting
• Inspector summary background
• Scene gizmos

ZoneSystemApi

The main entry point for runtime zone queries.

// Create the API with a reference to the ZonesObjectHolder
ZoneSystemApi api = new ZoneSystemApi(zonesObjectHolder);

// Full zone resolution at a world position
ZoneContext ctx = api.QueryZone(partyWorldPosition);

if(!ctx.isSafe && Random.value < ctx.finalEncounterChance)
    TriggerEncounter(ctx.encounterTableId, ctx.finalDifficultyTier);

Methods

ZoneContext Struct

Dynamic Zones

// After instantiating a zone at runtime:
api.Register(zoneInstance);

// Before destroying:
api.Unregister(zoneInstance);

Enums

ZoneRole

ZoneShape

DifficultyTier

MapPlane

ScriptableObjects

ZoneData

Per-zone configuration asset. Created via the Zone Editor or Create → ZoneSystem → Zone Data.

MonoBehaviours

ZoneInstance

Placed on a scene GameObject. References a ZoneData asset and provides spatial queries.

ZonesObjectHolder

Scene manager that holds the map plane setting and provides access to all zones.

PolygonUtils

Static math utilities for polygon operations.

MapPlaneUtility

Converts between 3D world positions and 2D plane coordinates.

ShapeFactory

Generates default polygon vertices for each shape type.

ZoneResolver

Pure logic for resolving overlapping zones into a single ZoneContext.

ZoneExporter

Serializes scene zones to a JSON structure for runtime loading.

In the Zone Editor window, expand Export Zones to JSON, set the output path, and click Export Now.

Loading at Runtime

string json = File.ReadAllText(Application.streamingAssetsPath + "/zones.json");
ZoneExportRoot root = JsonUtility.FromJson<ZoneExportRoot>(json);

Export Structure

Each zone is exported as a ZoneExportEntry containing all zone data fields plus the world-space polygon coordinates and transform position.