Skip to content

Character Catalog and Previews

A Character Catalog is your ordered collection of selectable CharacterDefinition assets. Each definition has a stable Character ID, a display name, Gameplay Prefab and optional preview/portrait settings. Catalog order controls browsing, not identity. Begin with Quick Start; configure lobby UI with Chapter 5 — Lobby Templates and Existing Canvas.

Create or choose a catalog

  1. Open Tools > LevelArgento > Couch Co-op Builder > Character Catalog Generator, or Generate from Prefabs... in the Wizard's Characters step.
  2. Add your playable prefab assets using Add Slot or Add Selected Prefabs. Choose an existing Output Folder under Assets.
  3. Choose Create a new Character Catalog and its name, or assign Existing Catalog to append eligible definitions.
  4. Review Plan lists creation/reuse decisions and any blocking problems. Generate Reviewed Assets creates the reviewed definitions/catalog without modifying source prefabs or overwriting existing assets. Saved disk assets are not guaranteed to reverse with Undo.
  5. Assign the resulting catalog to the Wizard, or select an existing catalog in its Character Catalog field. Inspect its definitions and use Run Catalog Validation before testing selection.

You can also create Character Catalog/Character Definition assets from Unity's Create > Couch Co-op Builder asset menu and assign definitions manually. Keep Character IDs nonempty and unique. Renaming display names or reordering entries need not change IDs; changing an ID breaks existing references to that selection. Reuse the established ID when updating a definition.

Validation and selection state

Use a nonempty catalog with no null/duplicate entries, blank/duplicate IDs or missing Gameplay Prefabs. The built-in lobby selection requires that valid catalog even when your gameplay later binds existing objects or uses a custom provider. The Wizard may allow Apply with a missing-prefab warning; assign those prefabs before expecting lobby confirmation to succeed.

If an ID no longer exists, is ambiguous or its catalog is missing, the gameplay context reports unresolved character metadata instead of inventing a substitute. Correct the definitions/catalog, validate, and select again. API-only gameplay metadata lookup does not require a prefab; selected-character spawning does. See Gameplay Integration for that distinction.

SelectedCharacterId belongs to the joined session and persists through lobby/gameplay transitions until permanent Leave. Ready belongs to the lobby scene and resets on reconstruction. Preview focus, committed selection and Ready are separate: browsing/moving focus alone does not commit a Character ID or clear Ready. Confirm commits the choice; external committed-selection/catalog changes can invalidate Ready.

Preview host

CharacterPreviewHost is a scene-local runtime presenter. It accepts a CharacterDefinition, creates a presentation-only clone, frames its child renderers, and exposes a small RenderTexture suitable for any lobby view.

Public API

  • Show(CharacterDefinition) displays or replaces the active definition.
  • RefreshPresentation() recalculates framing without replacing the clone.
  • Clear() releases the clone, camera, light, RenderTexture, and runtime layer lease.
  • SetOutputSize(width, height) adjusts the bounded 64-1024 pixel output.
  • ActiveDefinition, ActiveInstance, OutputTexture, FallbackPortrait, DisplayMode, and StatusMessage expose current presentation state.
  • PresentationChanged lets a layout update its prefab, portrait, or placeholder view.

The host does not know about player sessions, input, Ready state, scene loading, or a specific lobby layout.

Prefab and fallback resolution

The host uses CharacterDefinition.SelectionPreviewPrefab. That property resolves an explicit preview prefab first and otherwise returns the gameplay prefab. If neither is available, or if the resolved prefab has no child Renderer, the host exposes the definition's portrait. When no portrait exists, DisplayMode.Placeholder preserves the character name and a reason through the consuming view.

MeshRenderer, SkinnedMeshRenderer, SpriteRenderer, and other Renderer subclasses are discovered on all children. An Animator is optional. Its controller's default state plays normally; Preview Settings > Animation State can request an existing state without requiring a humanoid rig or a LevelArgento-specific controller.

Framing

All child renderer bounds are combined, including off-center children. Perspective framing accounts for texture aspect ratio and expands when an animated pose exceeds the original bounds. Per-character settings provide position, rotation, scale, framing padding, and an optional Animator state/layer. These adjustments affect only the runtime clone.

Camera and resource isolation

Each active host owns one disabled camera, directional light, and 256x256 RenderTexture. The camera renders manually only while that host's renderers are temporarily enabled. The host automatically leases an unused, unnamed runtime layer rather than requiring a fixed project layer or changing TagManager settings. Other preview hosts remain disabled during that render, so player previews cannot render each other's instances. The camera never reads or modifies the customer's Main Camera.

The host releases all native and scene objects on Clear, disable, destruction, Leave, and scene teardown. It does not create a camera or texture per catalog entry.

Gameplay prefab fallback limitations

A gameplay prefab can contain scripts, input components, physics, audio, or other match-only behavior. The host instantiates it beneath an inactive runtime root, disables all cloned MonoBehaviours, physics collisions/simulation, and play-on-awake audio before activating the clone, and leaves Animator components available.

Unity invokes a cloned MonoBehaviour's Awake during Instantiate before the host can disable that component. OnEnable, Start, and later callbacks remain suppressed, but gameplay prefabs with unsafe Awake logic are not suitable as direct preview fallbacks. Other component-specific initialization can also have side effects. Assign a dedicated SelectionPreviewPrefab when a gameplay prefab is expensive, depends on gameplay services, or contains behavior that should never exist in a lobby. The source prefab and its assets are never modified.

Lobby integration

The supplied lobbies create one preview host per joined panel. Browsing changes only that host's presentation. Confirming uses CharacterSelectionService to commit SelectedCharacterId and set scene-local Ready. Leave clears the departing panel's preview; returning to the lobby reconstructs it without replacing the session or InputUser. See Lobby and Existing Canvas for authored view assignments.