Presentation-Only Consumption

The full addon includes both layers by default. This page covers the presentation-only package, in which the placement authority is omitted.

The full Grid Placement addon performs placement mechanics: the session, the host, candidate transforms, validity, committed world records, manipulation, and the lifecycle results those produce. An integration that already decides those facts — for example, a game whose own native simulation owns placement — can omit the mechanics and use only the visual feedback layer.

The addon is layered so that this is a physical split, not a policy promise.

The two layers

Authority layer (placement mechanics). Placement session state, candidate transform and cell/face/rotation/flip, placement validity, commit and lifecycle results, world/occupancy records, move/demolish workflows. Integrations that already decide those facts can omit them.

Presentation layer (visual feedback only). Renders a verdict the caller already made. It never computes validity, never owns a placement record, and never mutates placement state.

The presentation surface is:

File	What it gives you
resources/presentation/placement_presentation_profile_3d.gd	Data resource for ring and ghost visual response.
systems/building/3d/placement_contact_ring_3d.gd	Ground contact ring driven by update(parent, profile, ghost, valid).
systems/building/3d/shaders/placement_contact_ring.gdshader	Ring shader used by the ring class.
placement/rule_check_indicator/rule_check_indicator_3d.gd	Per-cell mesh that shows a set_valid(true/false) verdict.
placement/rule_check_indicator/indicator_visual_settings.gd	Valid/blocked materials and display policy.
systems/grid_targeting/highlight_settings.gd	Preview and invalid highlight colors.
ui/target_informer/target_info_settings.gd	Target label settings.
components/cursor_settings.gd	Cursor icon settings.
base/placement_resource.gd	Shared resource base for the settings above.

The presentation layer receives its truth as arguments or properties. It does not read a session, a host, a service, or a world registry.

Producing the presentation-only addon

The release repository ships an explicit exclusion manifest and a proof:

python3 scripts/release/stage_public_2d_plugin.py \
    --manifest scripts/release/presentation_only_excludes.txt \
    --output-root /path/to/your_project
python3 scripts/ci/presentation_only_proof.py

stage_public_2d_plugin.py copies the addon and deletes every authority path in the manifest. It fails closed if any retained file still references a removed class name or resource path, so a stray dependency cannot slip into a "presentation-only" copy.

presentation_only_proof.py stages the addon into a clean project, cold imports it, and runs a headless smoke that:

• checks that the host, session, services, runtime, manipulation state, and plugin entry point are physically absent;
• instantiates the profile, contact ring, validity indicator, and settings resources and exercises their public API.

If you maintain your own fork without the scripts, the same split is the file list above: delete everything else under addons/grid_placement/ and keep base/placement_resource.gd, icons/, and the files in the table.

Using the presentation surface

The caller supplies the verdict and the transform:

var profile:PlacementPresentationProfile3D = preload(
    "res://addons/grid_placement/resources/presentation/placement_presentation_profile_3d.gd").new()
profile.enable_contact_ring= true

var ring:= PlacementContactRing3D.new()
ring.update(preview_root, profile, ghost_mesh, is_placement_valid)

is_placement_valid is the caller's result. The ring copies the ghost's transform and the boolean; it never checks occupancy, rules, or terrain.

For a validity mesh, configure valid_material and invalid_material on a RuleCheckIndicator3D and call set_valid() when the verdict changes. The node emits valid_changed.

What the presentation-only package omits

• No PlacementSession, host, input dispatch, or service group.
• No catalog, world registry, occupancy, or restore support.
• No PlacementLifecycleResult; identity and result contracts are the game's own.
• The presentation classes are the supported surface in this mode. The full addon also includes the placement mechanics; the game bridge guide describes integration patterns for them.

Verification in the release process

The release gate runs the staging check and the runtime smoke on every release, so a change that breaks the layer split fails before publication. The manifest is deliberately explicit (no globs): removing a file that shared presentation code fails the stage validator instead of silently dropping a class.