Presentation-Only Consumption

The standard Grid Placement addon includes both placement mechanics and visual feedback. This guide is for repository maintainers who want to stage a local copy with only the presentation layer; it is not a separate maintained plugin.

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 split is defined by an explicit exclusion manifest.

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.
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.

Stage a presentation-only copy

From the repository root, use the staging script and presentation-only manifest:

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

Use a disposable output directory. If addons/grid_placement already exists there, the script replaces it.

The script copies the addon, removes the paths in the manifest, then checks that retained files do not reference excluded classes or missing addon resources. It also validates GDScript and shader UID sidecars. It does not start Godot or test node behavior.

The normal public plugin archive uses public_2d_excludes.txt and keeps the full addon. The presentation-only manifest builds a separate local copy; it is not part of that archive path. The staging scripts are not included in the customer addon archive.

If you maintain a fork without the staging script, use the manifest as the source of truth for which paths to remove. Keep UID sidecars for retained scripts and shaders.

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 a staged copy 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 only Grid Placement classes in this copy. The full addon also includes the placement mechanics; the game bridge guide describes integration patterns for them.

What to verify

The staging script checks file references and UID sidecars. If you have the repository checkout, run its contract test. It stages the presentation-only manifest and checks that the profile remains while the host is absent:

python3 scripts/release/stage_public_2d_plugin_test.py

These checks do not import the staged copy in Godot. Before using it in a project, import the copy and instantiate the presentation resources and nodes your game uses.