BC-0229 · TROUBLESHOOTING
Editorial review 2026-09-27
Build Tutorial Is Unclear
If the player knows the goal but cannot follow the tutorial, map the instruction's nouns and verbs to controls and objects actually present in that state. A tutorial can be concise yet unusable when it names a missing control, assumes an untaught action or describes a state the player has not reached.
Symptom
A tutorial instruction cannot be mapped to an available action despite an understood goal.
Immediate action
Match its named target, input and prerequisite to the actual current interface.
Diagnostic branches
- The instruction names a different label from the existing control.
- Use truthful consistent wording without adding a duplicate action.
- A required earlier action was not taught or made recognizable.
- Introduce that prerequisite before the dependent instruction.
- The necessary control is genuinely absent.
- Treat it as missing functionality instead of declaring the copy fixed.
Least-destructive change
Correct the broken reference or prerequisite while preserving the real goal and valid existing controls.
Retest
- Every named action and target exists in the state where the instruction appears.
- The required prerequisite is available and understandable.
- Successful completion does not leave an obsolete instruction as the next command.
Escalation
Record the literal instruction-to-action gap if it remains unresolved. This does not establish physical-device usability or a tested tutorial completion rate.
Working notes
Read the instruction as a literal action request. Identify its target, required input and prerequisite. Press interact is not actionable if the game shows a differently named action or the current input method has no such visible control. Keep the actual device and interface state in the record.
Look for an unspoken prerequisite before expanding the text. A delivery instruction may assume the player already knows how to pick up an item. If that earlier action has never been introduced, repeating the destination instruction more loudly does not bridge the missing knowledge.
Repair the smallest broken reference or dependency. Use the control label and object cue that really exist, or teach the missing action before asking for the dependent one. Do not invent a button to make the sentence true; a missing required control is an implementation issue, not merely a copy edit.
Check the instruction at the moment it appears and after its action succeeds. It should not require an unavailable state or remain as a stale command after completion. For broader first-session observation and instruction lifecycle, use the tutorial refinement guide rather than claiming this text audit covers all onboarding.
Examples
- Reference failure: the tutorial says press Carry but the actual safe action is labeled Pick Up. Align the instruction with the genuine control; do not add a second unexplained control purely to match the old wording.
- Prerequisite failure: deliver the parcel appears before any instruction or affordance explains how to acquire it. Introduce that action first and retain the delivery goal, instead of adding more destination prose.