# Heads or Tails model guide

[Read as Markdown](/raw/game-model-coinflip.md) · [All game guides](/betting-models/) · [Measured native reference](/game-model-reference.json)

## Replacement skin support

This game supports the [v2 skin contract](/game-skin-contract/). Replace the visible body and the exact named physical meshes listed at the end of this page. Use the surround and trim suggestions below to add matching scenery. Preserve the functional regions and state-dependent clearances described here.

## Station identity

The player-facing game may be called Heads or Tails or Coinflip. Its asset is **`coinflip`**, with station IDs `coinflip:0` through `coinflip:4`. Use floor elevation Y = 0–64 and scale `[1,1,1]`. The native root is `coinflip` in the game library.

Preserve the supplied coin, pedestal and controls. A gold disc uploaded as a separate prop is static scenery; it will not inherit the native flip animation or become a wager target.

## Controls and readouts

| Region | Native behavior |
|---|---|
| Heads | Selects Heads; native choice index 0 |
| Tails | Selects Tails; native choice index 1 |
| Flip | Starts the configured wager |
| Stake − / + | Changes the configured stake when allowed |
| SET / settings surface | Opens supported bet controls |
| Coin surface | Also provides a native settings interaction |
| `result_display` | Shows the selected side, flipping state and settled result |
| `bet_display` | Shows the current stake |

The current physical buttons are measured in `games.coinflip.controls`. The native `coin`, `top`, `result_display` and `bet_display` references identify the artwork and live-display locations. Use the current GLB and generated reference together; a generic round-table diagram does not describe its control placement.

## Animation clearance

Leave space **above** the resting coin and around its full rotating shape. The rest-pose mesh bounds do not include its toss envelope. Do not add a low dome, hanging sign, foliage or decorative second coin in that volume. A still render can appear correct while the first animated flip clips through the new artwork.

Both faces must remain visually distinct and visible during the native animation. Do not rotate, mirror, rescale or swap the actual coin mesh in a downloaded reference and expect the runtime to adopt it. Do not bake an always-visible Heads or Tails result into decorative artwork. The native client reconciles the final face and displayed outcome with the game result.

## Original surround recipe

Use separate low pedestal accents, an outer side medallion or a small sign beyond the coin's travel. Keep the native top and its controls intact. Avoid an encircling shell whose box collider spans the player's approach. Keep front furniture low enough to reveal both the buttons and the result display from normal eye height.

Use a neutral or coordinated material palette around the selection buttons so the native selection highlight stays obvious. A custom decorative heads/tails emblem should not look like a second clickable choice bank. Use the approved `control.choice_0` or `control.choice_1` skin socket for a functional replacement; body decoration alone has no action.

## Review and AI brief

Inspect both selected sides, the start of the toss, the highest/rotating portion, landing on each face and the result readout. Confirm that the result and selected-side text are not confused. Check a portrait phone and a side view, not just a top-down render. Use an authorized preview for active animation; do not spend funds merely to check art.

```text
Get game_skin_contract for coinflip and download my current world draft.
Build an original [theme] replacement body in Blender using the reference socket
measurements and the preserved gameplay regions described in this guide.
Upload static body/button assets; bind only the listed control/part sockets.
Keep native labels, game values and collision. Use supported v2 placements, clips
and result-motion channels for presentation changes.
Save with game_skin_save and the current revision. Inspect the fitted model
and report budgets and reviewed states. Do not upload code or publish via MCP.
```

See [the shared authoring workflow](/model-authoring-workflow/) for export and alignment.


## Reference skin sockets (v1 and v2)

Read `game_skin_contract({"game":"coinflip"})` before saving. The current fingerprint is `4aeda6f64c6196b1`. The [live catalog](/game-skin-catalog.json) is authoritative if a copied example differs.

The replacement body is fitted to station-local world bounds `[-1.8820678, 0, -1.8820678]` through `[1.8820678, 2.2867124, 1.9651924]`. Width, height and depth are `[3.7641356, 2.2867124, 3.8472602]`. These values already include source scale. Entity scale remains `[1,1,1]`.

| Accepted binding slot | Fixed native action | Fixed index / seat | Native label | World-space bounds, minimum → maximum |
|---|---|---|---|---|
| `control.stake_up` | `stake_up` | None | + | `[-1.1901888, 1.5770159, 1.0979373]` → `[-0.9114535, 1.6789612, 1.3851821]` |
| `control.quick` | `quick` | None | FLIP | `[-0.893638, 1.577016, 1.1731573]` → `[-0.2983382, 1.6789613, 1.768457]` |
| `control.choice_0` | `choice` | index 0 | HEADS | `[-0.1802341, 1.577016, 1.3181641]` → `[0.3057053, 1.6789613, 1.8041035]` |
| `control.settings` | `settings` | None | SET | `[1.1092243, 1.5770159, 0.7276015]` → `[1.619774, 1.6789612, 1.2370141]` |
| `control.choice_1` | `choice` | index 1 | TAILS | `[0.4431057, 1.577016, 1.1039054]` → `[1.0625484, 1.6789613, 1.7233481]` |
| `control.stake_down` | `stake_down` | None | − | `[-1.4615017, 1.5770159, 0.8857512]` → `[-1.173393, 1.6789612, 1.1743036]` |

Only `slot` and the converted model `asset` hash go in each binding. Action, index and seat columns explain platform behavior; **do not copy them into uploaded JSON**. All listed sockets are optional visual overrides. Omitted sockets retain native meshes. Repeated Settings actions are distinct physical sockets and must use the exact listed ID. The catalog provides exact mesh-local `localBounds` for fitting and the full `matrixSource` for native orientation.

Optional static surface: `part.playing_surface`, native reference `top`, world bounds `[-1.6185782, 1.3927301, -1.5056542]` through `[1.6185782, 1.4115508, 1.5056542]`. Its replacement does not move cards, the animation rig or the interaction proxy.

Save a skin with `game: "coinflip"`, its current fingerprint, a converted `body` hash and the chosen `bindings`. Apply it only to existing `coinflip:<index>` entities. Declare each binding in the skin manifest. Follow [the exact manifest and fitting rules](/game-skin-contract/) and [the export workflow](/model-authoring-workflow/).

## V2 layout and animation

Fetch `game_skin_contract({"game":"coinflip"})`. Use `presentation.targets` to position the body, complete display and each listed physical control. Control labels and clickable proxies follow their target; action/index/seat identity stays the same. Numeric `idle` and `result` clips are supported. Its result-motion channels are `coin_flip`. Use the per-result progress and zero endpoint offsets described in the contract. Reference dimensions above describe the neutral layout before v2 placement. See the [exact fields, transforms and limits](/game-skin-contract/).