Skip to content

Quest Dialogue Writing Guidelines (Ages 6+)

These rules standardize quest Yarn script text for young learners (~6 years old). Apply them BEFORE translating. Keep all technical markers intact.

1. Do NOT Touch Technical Elements

  • Keep every #line:HASH exactly as-is (hash, spacing, position)
  • Do not rename nodes, tags, or commands (<<task_start>>, <<card ...>>, etc.)
  • Do not remove or reorder commands around a spoken line
  • Only edit the spoken text BEFORE the #line: token

2. Sentence Shape

Rule Target
Words per sentence 5–12 (max 15 only if colors/list)
Tense Present simple
One idea per sentence Yes
Punctuation Every spoken line ends with ., ?, or !
Exclamations Max 1 per short exchange

3. Vocabulary & Tone

  • Prefer high-frequency words: help, find, friend, flag, big, small, red, blue
  • Replace advanced verbs: discover → find, claim your victory → get your prize
  • Allow ONE cultural greeting per country (Bonjour / Hola / Ciao / Danke / GrĂĽezi / Moien). After first use revert to “Hello”
  • Keep cultural nouns (Rome, Madrid, flamenco) but simplify surrounding sentence
  • Avoid idioms or abstract metaphors

4. Flags & Colors

  • Keep correct color order (do not improvise)
  • Standard pattern: It has stripes: black, red, yellow. OR It is red and white.
  • Limit comparisons: one simple image max (e.g., “like a pizza”)

5. Consistent Patterns

Context Pattern
Greeting Hello! I'm from COUNTRY! (or first line with local greeting)
Ask help Can you help my COUNTRY friend?
Task intro Find the COUNTRY flag.
Completion Good job! / Thank you!

6. Capitalization & Spelling

  • Nationalities & countries capitalized (German, Spanish, Swiss, Luxembourg)
  • Colors lowercase (unless start of sentence)
  • Fix typos immediately (yellow, Luxembourg)

7. Simplification Steps (Apply in Order)

  1. Fix typos & capitalization
  2. Shorten long sentences (split if > 15 words)
  3. Replace rare words / complex verbs
  4. Standardize patterns (greeting, help, task, completion)
  5. Ensure punctuation
  6. Remove redundancy (“the French one” → “my flag”)
  7. Final pass: word count & clarity

8. What NOT to Change

  • Factual information (capital cities, counts, geography)
  • Educational objectives or task logic
  • Inventory and task progression commands

9. When a Line Is Too Complex

Issue Fix Example
Too many clauses Split into two lines (if allowed)
Abstract phrase Replace with concrete (“claim your victory” → “get your prize”)
Cultural overload Keep one key detail

10. Placeholders / Missing Translation Handling

  • English source should never include placeholders
  • If a translation later missing: exporter shows English (or [MISSING TRANSLATION: original] for non-English builds)

11. Quality Checklist (Pre-Commit)

  • [ ] All #line: tags unchanged
  • [ ] Every spoken line has punctuation
  • [ ] No sentence > 12 words (except color list)
  • [ ] No double spaces, no stray leading/trailing spaces
  • [ ] Greetings pattern correct
  • [ ] Color descriptions concise & accurate
  • [ ] No new complex vocabulary slipped in

12. Optional Change Tags (For Internal Review)

Add inline comment (removed in final) if needed: - [VOCAB_SIMPLIFY] rare word replaced - [CULTURE_TRIM] extra cultural detail removed

13. Examples

Before: 

Antura made a mess and all the flags have been mixed up! #line:XXXXXXX
After: 
Antura mixed up all the flags! #line:XXXXXXX

Before: 

Go back to the start and claim your victory! #line:YYYYYYY
After: 
Go back to the start and get your prize! #line:YYYYYYY

14. Edge Cases

Case Guidance
Emotional emphasis One exclamation OK; avoid stacking (!)
Lists > 3 colors Keep if flag pedagogy requires
Foreign word confuses context Replace with English after first exposure

15. Rationale

These constraints support early readers: predictable syntax, limited working-memory load, reinforcement of factual patterns (flags, capitals), and easy translation alignment.

version for AI

You rewrite child learning game dialogue for 6-year-olds. Keep every #line:HASH tag unchanged at end of its line. Only edit text before the tag. Keep Yarn commands (<< >>) and structure exactly. Rules:

Present simple. 1 idea per sentence. 5–12 words (15 max if color list).
End every spoken line with . ? or !
High-frequency words only (help, find, flag, friend, big, small, red, blue). Replace complex words: discover→find, victory→prize.
One cultural greeting per country (Bonjour/Hola/Ciao/Danke/GrĂĽezi/Moien) then use Hello.
Keep factual info (capitals, colors) and order of colors.
Flag colors format: “It has stripes: black, red, yellow.” or “It is red and white.”
Ask help: “Can you help my COUNTRY friend?”
Task: “Find the COUNTRY flag.”
Completion: “Good job!” or “Thank you!”
Capitalize countries/nationalities. Colors lowercase (unless sentence start).
Fix typos. Remove redundancy (“the French one” → “my flag”).
No idioms, no abstract metaphors, no multiple exclamations.
If sentence >12 words, split or simplify.
Do not add new facts.
Checklist before output:

All #line: tags identical
Punctuation present
Each line within word limit
No new complex vocabulary
Color facts correct
Output only the modified script text with original unchanged lines preserved except where simplified.

Last updated: 2025-09-07