Tiled Prefab Import And Placement

Purpose

Tiled prefab import turns reusable TMX snippets into scene edits with predictable layer placement, origin handling, validation, and undo behavior.

How It Works

The prefab parser reads supported TMX tile layers and object groups. The planner decides how those layers should be inserted into the target scene using insertion policy, insertion band, append-after, or merge-matching-role rules. The apply step mutates the scene through editor history so prefab placement can be undone.

Unsupported image layers or groups should become warnings, not silent content.

Steps

Store prefab assets under the expected asset-root layout and keep tileset paths resolvable from the prefab. Name layers so the planner can infer the intended scene role. Choose an insertion policy before applying the prefab, then inspect the cleanup preview and validation report.

Use occupied origin and placement origin deliberately. They determine where imported tiles land relative to the target scene.

Expected Outputs

A successful import produces scene edits on the intended layers, valid object placements, a clean cleanup preview, undoable history, and a scene validation report that does not introduce prefab-related errors.

Invariants

Prefab import must not bypass scene validation. Layer role inference should match the same semantics used by regular scene import. Undo history must capture the scene mutation. Warnings about unsupported TMX content should be resolved before a prefab becomes shipped content.

Common Mistakes

Common mistakes include broken tileset paths, layer names that infer the wrong role, choosing the wrong insertion band, ignoring unsupported TMX warnings, or placing from the wrong origin.

Recovery Paths

Missing tilesets, unexpected layer bands, unsupported object groups, and origin mistakes are the common failure modes. Validate the prefab asset first, then validate the scene after placement.