Game Bridge Recommendation

A game bridge is useful when one build action must coordinate Grid Placement with several game systems, such as ownership, economy, construction progress, faction rules, AI tasks, or save IDs.

It is optional. A simple game can call Grid Placement directly.

Use a bridge when it removes repeated integration code

Good reasons:

several game systems need one game-specific build operation;
a successful placement must create or update a game entity;
faction or player ownership must be attached to committed placement;
construction, cost, or progression rules belong to the game;
your save system maps plugin placement_instance_id to a separate game building/entity ID;
you want plugin-specific types isolated from a large simulation module.

Do not add a bridge because of an arbitrary call-count or file-length threshold.

Keep placement state in one place

A bridge translates between game logic and Grid Placement. It should not create a second placement database.

game request/policy
→ game bridge/BuildingAuthority
→ Grid Placement preview/validate/commit
→ typed placement result
→ game updates game-owned state

Grid Placement tracks reusable placement facts:

target and placement validity;
committed placement identity;
GRID and SMOOTH occupancy;
CELL/EDGE/FACE/CORNER mount occupancy and SMOOTH socket occupancy;
placement transform, mount, and support data;
placement-world restore.

Your game tracks game-specific state:

ownership and factions;
construction progress;
costs and resources beyond the placement integration;
game entity/building IDs;
AI and pathfinding consequences;
game save schema and progression.

Avoid parallel occupancy state

Do not keep a bridge-side _occupied dictionary that mirrors Grid Placement occupancy.

If the game needs its own spatial data for gameplay, define what that data represents and reconnect it through stable placement IDs or placement results. Do not copy plugin occupancy internals into another registry.

Prefer game-specific operations

A bridge is most useful when it exposes game actions instead of wrapping every plugin method.

Example shape:

class_name BuildingAuthority
extends Node

signal building_committed(building_id:int, placement_id:StringName)
signal building_rejected(reason:String)

func request_build(owner_id:int, entry_id:StringName, target)-> void:
    # 1. Check game-owned permissions/cost policy.
    # 2. Submit through the supported Grid Placement API.
    # 3. On commit, create/update the game-owned building record.
    pass

The target and result types can differ between 2D GRID, 3D GRID mounts, and SMOOTH placement. Do not force every dimension through an invented dictionary wrapper only to make the bridge interface look uniform.

Use providers or rules for read-only facts

If Grid Placement only needs to read a game fact during validation, a custom placement rule or world-facts provider is often smaller than a full bridge.

Examples:

protected build zone;
technology unlocked;
2D reserved cell;
inventory availability.

Use a bridge when the game must coordinate a larger lifecycle around committed placement.

Save/load mapping

Keep plugin placement identity and game entity identity distinct:

placement_instance_id ↔ game building/entity id

Persist that mapping in your game save layer. Let Grid Placement restore placement records, then reconnect your game-owned fields through the stable mapping.

Anti-patterns

Avoid:

bypassing Grid Placement validation or occupancy from the bridge;
re-exporting private/internal service objects as your game's public API;
duplicating placement records in unsynchronized dictionaries;
putting faction, economy, or construction types into the reusable addon;
wrapping every plugin method one-for-one without adding a useful game-specific operation.