# Unity playable-game implementation: Milk

Concept key: `milk`  
Concept type: `object`  
Category: `food.drink`  
Status: implementation brief; SLP, accessibility, language/cultural and safeguarding review required.

## Outcome

Build one reusable Unity scene that can run five data-driven activities for `Milk`. The game must teach or assess the concept without requiring speech, audio, reading, colour discrimination or rapid motor responses. It must work with touch, mouse, keyboard/switch scanning and clinician-assisted pointing; enable AAC, eye-gaze and observed-response adapters when configured.

## Recommended Unity baseline

- Unity 2022.3 LTS or later LTS; Universal Render Pipeline is optional, not required.
- uGUI or UI Toolkit, with all interaction behind an `IResponseInput` interface.
- Addressables for images/audio; Unity Localization package for strings and locale assets.
- New Input System for touch, mouse, keyboard, gamepad and switch scanning.
- JSON content loaded from StreamingAssets or a remote immutable content bundle.
- No third-party analytics, advertising, accounts, chat, purchases or network dependency in the learner scene.
- Target 60 fps, but all success logic must remain frame-rate independent and untimed by default.

## Scene and prefab structure

```text
Scenes/
  SpeechGame.unity
Prefabs/
  StimulusCard.prefab
  ChoiceGrid.prefab
  PromptPanel.prefab
  FeedbackOverlay.prefab
  ProgressDots.prefab
  PauseAndStop.prefab
Scripts/
  SpeechGameController.cs
  TrialDirector.cs
  ContentLoader.cs
  DifficultyAdapter.cs
  PromptController.cs
  ResponseInputRouter.cs
  AccessibilitySettings.cs
  TrialEventWriter.cs
ScriptableObjects/
  ConceptGameDefinition.asset
  ReinforcementProfile.asset
Tests/
  EditMode/
  PlayMode/
```

Use a single `SpeechGame` scene. The controller receives `conceptKey=milk`, `gameKey`, `language`, `accessProfile`, `sessionSeed` and optional clinician overrides. Do not create concept-specific game logic; `milk` is content data.

## Required content binding

- Target images: `../images/milk_isolated_01.png`, `milk_natural_context_01.png`, `milk_variation_01.png`, `milk_viewpoint_01.png`, `milk_context_complex_01.png` and `milk_unfamiliar_01.png`.
- Text: load semantic keys from `../text/` and approved child-facing strings from `../locales/<language>/`.
- Spoken prompts: optional approved files from `../locales/<language>/audio/`; never make audio the only cue.
- Concept game data: `game-briefs.json`; production tracking: `games-list.csv`.
- Sample screen reference: `milk_unity_game_sample_01.png` in this folder. It is a visual direction reference, not a shippable UI asset.
- Verify asset checksums and reject missing or unknown keys before entering a trial.

## Applicable learning nodes

- make_choice
- recognize_familiar_object
- identify_familiar_object
- request_desired_object
- label_familiar_object
- combine_request_object
- establish_access_profile
- match_object_to_object
- match_object_to_photo
- follow_one_step_instruction
- imitate_environmental_sound
- combine_action_object
- combine_descriptor_object
- answer_what
- describe_scene

## Five required game modes

- `milk_find` — template `single_choice`, purpose `identify`, difficulty 1; distractors: unrelated clear contrast; responses: touch, pointing, eye_gaze, aac.
- `milk_match` — template `image_match`, purpose `match`, difficulty 1; distractors: one valid match plus clear non-match; responses: touch, pointing, eye_gaze.
- `milk_discriminate` — template `discrimination`, purpose `discriminate`, difficulty 2; distractors: same category only after clear contrast succeeds; responses: touch, pointing, eye_gaze, aac.
- `milk_use` — template `natural_routine`, purpose `functional_use`, difficulty 2; distractors: meaningful choices in a real routine; responses: gesture, aac, sign, vocalisation, speech, observed.
- `milk_novel` — template `probe`, purpose `generalisation`, difficulty 3; distractors: novel exemplar and balanced position; responses: touch, pointing, eye_gaze, aac, gesture, speech.

Implementation behavior:

1. **Find:** show one target and one clear unrelated distractor. Prompt using the approved semantic instruction. Randomize left/right while preventing more than two identical target positions in succession.
2. **Match:** show a reference card above two choices. A valid different exemplar of `Milk` is the match; do not match an image to an identical duplicate unless the learner is at the earliest access stage.
3. **Discriminate:** use two to four choices. Start with clear-category distractors; unlock same-category and context-rich distractors only after success. Never use colour or screen position as the answer cue.
4. **Use:** place `Milk` in a meaningful scene or routine. Accept configured touch, pointing, gesture, sign, AAC, vocalisation, speech or clinician-observed response; speech recognition must never be authoritative.
5. **Novel probe:** use `milk_unfamiliar_01.png` or another approved unseen exemplar, give no corrective teaching during the scored probe, balance position and record it separately from teaching trials.

## Trial flow

`Load -> Ready -> Present stimulus -> Wait for response -> Record raw response -> Apply prompt/feedback -> Inter-trial pause -> Next or Stop`.

- Default field size: 2; configurable 1–4.
- No countdown. Default response window is unlimited; an optional clinician timeout records `no_response`, never `incorrect`.
- Lock choices only after a valid activation. Debounce duplicate touch/switch input for 300 ms.
- Correct response: gentle visual highlight and optional short neutral sound; no confetti storm or flashing.
- Incorrect response: no buzzer, red X, loss of points or negative language. Pause, reduce choices or provide the configured least-intrusive prompt.
- Offer an always-visible Stop/Pause control. Stop immediately on distress, fatigue or clinician action and preserve completed trial data.
- Use deterministic `sessionSeed` randomization so a session can be replayed exactly.

## Prompt hierarchy and adaptive difficulty

Prompt levels, from least to most support: independent, natural cue, visual cue, gesture, verbal cue, partial model, full model, physical assistance. Store raw correctness separately from independence.

- Increase difficulty after three consecutive independent correct trials across at least two target exemplars.
- Reduce field size or distractor similarity after two consecutive errors, two no-responses, or clinician-observed distress.
- Hold difficulty when correctness rises but prompt dependence increases.
- Never automatically advance on prompted correctness alone.
- Clinician override must be immediate and included in the event record.

## Accessibility and safeguarding

- Minimum interactive target: 96 x 96 logical pixels; minimum spacing: 24 pixels.
- Support large-card mode, high contrast, colour-independent focus outline, reduced motion, mute, captions and replay.
- Provide single-switch auto-scan with configurable 1–10 second interval and manual step-scan.
- Keep the selected item highlighted for at least 800 ms; never rely on a transient animation.
- Eye-gaze dwell is configurable and disabled by default; expose a cancel/dwell-reset action.
- Avoid drag-only interactions; every drag action needs tap-select/tap-destination and switch alternatives.
- Never display identifiable learner data, ads, external links or competitive leaderboards.
- Reinforcement is calm and age-respectful. Do not withhold communication, food, breaks or preferred items.

## Localization

- UI stores semantic keys, never embedded English. Use `milk.label`, `milk.instruction.identify`, `game.feedback.correct`, `game.feedback.try_again`, `game.pause` and `game.stop`.
- Allow text expansion to 200%, right-to-left layout, locale fonts and line wrapping without clipping.
- Voice and text may be independently enabled. The selected response mode must remain valid when audio is unavailable.
- Require native-language and SLP approval before marking a locale production-ready.

## Trial event contract

Write one append-only JSON object per presented trial:

```json
{
  "schema_version": 1,
  "session_id": "pseudonymous-local-id",
  "session_seed": 0,
  "concept_key": "milk",
  "node_key": "one-applicable-node-key",
  "game_key": "milk_find",
  "language": "en",
  "stimulus_asset_key": "milk_isolated_01",
  "choice_asset_keys": [],
  "target_index": 0,
  "response_mode": "touch",
  "raw_response": null,
  "correct": null,
  "prompt_level": "independent",
  "attempt": 1,
  "latency_ms": null,
  "difficulty": 1,
  "clinician_override": false,
  "stop_reason": null,
  "timestamp_utc": "ISO-8601"
}
```

Store locally using the host application's approved privacy layer. Do not put names, recordings, free text or medical identifiers in the event.

## Sample-screen composition

Use a calm 16:9 landscape layout: neutral warm background, small progress dots at top, short localized prompt area, two or three large rounded stimulus cards in the center, persistent replay/accessibility/pause controls, and a reserved feedback region. The sample must depict `Milk` as the selected target with one clinically sensible clear distractor. Avoid embedded words in the generated mockup so it can guide all languages.

## Definition of done

- [ ] All five game keys load from `game-briefs.json` without code changes.
- [ ] Six target exemplars and approved distractors resolve by stable asset key.
- [ ] Touch, keyboard, switch scan and clinician-observed paths pass PlayMode tests.
- [ ] Audio-off, reduced-motion, high-contrast, large-card and RTL layouts pass.
- [ ] Position balancing and deterministic replay tests pass for 100 seeded sessions.
- [ ] Correctness, prompt, independence, latency and stop reason are recorded separately.
- [ ] Missing assets/localization fail safely before a learner trial.
- [ ] SLP, accessibility, cultural/language, privacy and technical reviews are recorded.
- [ ] `games-list.csv` is populated with owner and review status before release.

## Required automated tests

1. Load every game key and locale without exceptions.
2. Assert exactly one target per scored choice trial.
3. Assert target position balance stays within 10% over seeded runs.
4. Assert no more than two identical target positions consecutively.
5. Assert timeout produces `no_response`, not `incorrect`.
6. Assert prompted correctness does not count as independent mastery.
7. Assert Stop works during every state and writes a final stop event.
8. Assert missing audio still leaves a complete visual/non-speech path.
9. Assert all controls remain reachable at 200% text and large-card settings.
10. Assert no personally identifying fields are serialized.