Game Screens

Layout rules Open page

All sizes are in points on the 844 × 390 pt reference screen (iPhone 12 to 14 in landscape). Other phones scale from it; see "Scaling" below.

Thumbs cover the bottom corners (AGENTS.md). In landscape the player holds the phone with both hands, and the thumbs rest about a fifth of the way in from each side, low down.

• Thumb corners: the bottom-left and bottom-right 190 × 156 pt (22% of the width, 40% of the height). Nothing fixed goes there: no buttons, no text you need to read, no status. Scrolling content (a list, a page of notices) may pass under them, as long as nothing in it can only be reached there.
• Stage: x 190–654, y 0–234. What the screen is about and its primary action go here.
• Top rails: the top-left and top-right corners inside the safe area. System actions live here, the same on every screen: Back top-left, Close top-right, and in the field the objective tracker (top-left), Map and Pause (top-right). A thumb reaches them with a stretch, which suits actions used now and then.
• Between the thumbs: x 190–654 below the stage. The dialogue box, captions and secondary actions. Choices, quest text and the main button stay in the stage.
• Drawing zones: in battle, field casts and practice, the whole lower half on each side of the centre line is where each thumb draws. UI drawn there must ignore touches (today UiScale.Block/IsBlocked; VEL-72 wires UI Toolkit into the same rule).

Safe area and the sensor housing. Velan runs in both landscape orientations (allowedAutorotateToLandscapeLeft and Right are on), so the notch or Dynamic Island is on the left or the right depending on how the phone is held, and layouts must mirror cleanly. The reference phone's landscape insets are 47 pt left and right and 21 pt at the bottom (the home indicator); Dynamic Island models use 59 pt left and right. Always read Screen.safeArea at run time and never hard-code these numbers. Backgrounds, world views and scrims run to the screen edges; content and touch targets stay inside the safe area, plus a 12 pt margin.

Touch targets. At least 44 × 44 pt (Apple's minimum), with 8 pt between targets. Primary buttons are 48 pt tall. The visible shape may be smaller than the hit area, but the hit area never is. Today's IMGUI canvas is 540 units tall, so 44 pt is 61 to 64 units depending on the phone.

Type. Body text at least 15 pt and captions at least 12 pt at the Standard text size. Every screen must still lay out at the largest text size (section 6, Accessibility), with lines wrapping, not cut off.

Scaling. For UI Toolkit (VEL-72): PanelSettings scale mode "Scale with screen size", reference resolution 844 × 390, match height. A taller or wider phone then gets more room at the sides, not bigger buttons, and 44 pt stays 44 pt on every iPhone in landscape.

Layers (one UIDocument each, as VEL-72 plans): HUD, screens (a stack), modal, toast, and the fader above everything. A modal blocks every layer under it. Screens in the menu pause the game (Time.timeScale = 0); the HUD and toasts never do.

Navigation. Back (top-left) pops the stack, and Close (top-right) leaves the whole menu and resumes play. There are no edge swipes, because they fight with drawing. Every screen that changes something saves at once; there are no Save buttons, except Save and quit.

Navigation map Open page

The map is drawn from navigation-map.dot (Graphviz). In words:

• Boot: iOS launch screen → Splash and boot → Title.
• Title: Continue (when there is a save) → Loading → Field. New game → Confirm replace (only over a save) → Body type → Name → Loading → Field. Settings ⇄ Third-party notices. Practice battle → Battle → Title.
• Field: the Field HUD is the hub. Talking or using something opens Dialogue, which can open a Shop, a Field cast or a battle. Exits go through Loading to the next location. Encounters push a Battle over the location; its Results return to the field. Toasts appear over the HUD.
• Menu: Pause opens Journal, Map, Spell book and Inventory, which share one tab bar so you can move between them without going back. Spell book → Spell detail → Practice. Inventory → Item detail → Letter viewer. Settings. Save and quit → confirm → Title.
• Shortcuts: the objective tracker opens the Journal on the tracked quest; the Map button opens the local map; tapping a toast opens what it is about (Journal, spell detail or item); Shop's Sell tab reads the same bag as Inventory.
• Confirm dialog: a modal over any screen, for anything that can't be undone.

What exists today Open page

The game screens today are IMGUI, drawn on UiScale's 540-unit virtual canvas. VEL-72 moves production screens to UI Toolkit and keeps IMGUI only for the debug panel.

Not on screen at all yet: splash (beyond Unity's), field HUD (objective tracker, map button), toasts in the field, journal, map, inventory, item detail, letters viewer, shop, battle rewards, loading card, confirm dialog.

Data each screen needs that doesn't exist yet Open page

Boot and title Open page

Splash and boot

• Purpose: cover start-up and show the studio and the game's name.
• In / out: the iOS launch screen (a static storyboard, VEL-80) hands over to it; it replaces itself with the Title.
• Shows: the Velan wordmark, "Original Function", a thin progress bar and "Loading".
• Actions: none; taps do nothing.
• States: loading is the screen. Error (game data won't read): "Velan couldn't start. Try again." with Try again, which reruns boot.
• Data: reads the game data, the save slot (to set up the title) and the saved settings, which it applies.
• Notes: aim for under 2 s on device. The Boot.startLocation developer shortcut skips the title, as today.

Title

• Purpose: start or resume a game.
• In / out: from Splash, or from Save and quit. Out to Continue (Loading), New game, Settings or Practice.
• Shows: title art (a still or a slow camera over Sallowbank), the wordmark, the Continue card when there is a save, New game, Settings, Practice, and the version at the bottom centre.
• Actions: tap the Continue card; New game; Settings; Practice.
• States: no save: no card, so New game moves to the top. Corrupt and newer version: see Continue. Starting: every button disables and the card shows "Loading…" until the fade.
• Data: reads SaveStore.Load(); the save's location, play time, level and update time; the quest log for the stage line.

Continue

Continue is a card on the Title, not a screen of its own: there is one save slot, so a list would only add a tap.

• Purpose: tell the player where they left off and take them back there.
• In / out: tap the card → Loading → the saved location and spawn point.
• Shows: the location's art thumbnail and name, the main quest's current stage, the level, play time and how long ago it was saved.
• Actions: tap to load.
• States: ready; loading (card dims, other buttons disable); couldn't be read (SaveSlotStatus.Corrupt): no Continue, with the notice "Your save couldn't be read. New game will replace it."; newer version (NewerVersion): "Saved by a newer version. Update Velan to continue it." with a link to the App Store page; load failed after the tap: the card returns with "Couldn't load. Try again."
• Data: reads the save (SaveGame.Location, PlaytimeSeconds, UpdatedUtc, Profile.Level, Flags). Writes nothing until the game is entered.

New game: confirm replace

• Purpose: stop a player wiping their save by accident.
• In / out: New game when the slot holds anything (HasSave). Keep my save goes back to the Title; Start over goes on to Body type.
• Shows: "Start a new game?" and what will be lost: "Your save in Sallowbank (Level 2, 0:42 played) will be replaced. You can't undo this." A newer-version or corrupt save gets its own line (see the frame).
• Actions: Keep my save, Start over (destructive: heavy outline).
• Data: reads the slot. Nothing is deleted until the new game is written, after the name.

New game: body type

• Purpose: choose the protagonist's body.
• In / out: from Title or Confirm replace; Next to Name; Back to where it came from.
• Shows: "Who are you?", "Step 1 of 2", two cards with the model turning slowly, labelled as today (Male, Female) until Ray decides (open question 2).
• Actions: tap a card to select it; Next (disabled until one is selected).
• States: model loading: the card shows its label and a placeholder silhouette.
• Data: holds the choice in memory; PlayerProfile.BodyType is written with the new game.

New game: name

• Purpose: name the protagonist, whom the villagers address by name.
• In / out: from Body type; Begin creates the save and goes to Loading → Sallowbank (farm_bed); Back returns to Body type, keeping the choice.
• Shows: "What's your name?", "Step 2 of 2", a text field with the iOS keyboard up, a Random button, the rule ("1 to 12 letters…"), Begin.
• Actions: type; Random fills a name from the list; Begin (also the keyboard's Return key).
• States: invalid: an inline message under the field ("Enter a name"; "Letters, spaces, ' and - only") and Begin disabled. Saving: Begin shows a spinner; if the write fails, "Couldn't create your save. Try again."
• Layout: the keyboard covers the lower half in landscape, so the field and Begin sit in the top 200 pt.
• Data: writes PlayerProfile.Name and BodyType through GameShell.NewGame (which needs a name parameter), and the first save.

Settings

• Purpose: per-device options. One screen with four tabs: Sound, Controls, Accessibility, About.
• In / out: from the Title or from Pause; Back returns there. Credits and Third-party notices push from About.
• Actions: every change applies and is kept at once (PlayerPrefs); there is no Save button. Back saves PlayerPrefs to disk, as today.
• States: none to load. A setting a device can't support (haptics on an iPhone without a Taptic Engine) is hidden.
• Data: reads and writes velan.settings.* in PlayerPrefs. None of it is in the save file, so a new game keeps the player's settings.

Sound: Master, Music, Effects and Ambience, 0 to 100 each. Letting go of Effects plays a short sample. Needs the audio mixer groups from VEL-84.

Controls:

• Haptics on or off: a tick when a stroke starts, a pulse on a cast, a buzz on a fizzle and when you're hit.
• Handedness, Right or Left. Left mirrors the HUD: the movement stick moves to the right half, and the top-rail buttons swap sides (Back and the tracker top-right; Map, Pause and Close top-left). The two drawing zones don't move.
• Swap thumbs in two-shape spells (left-handed mirroring): for asymmetric spells, whose thumbs draw different shapes (Facet Seal's circle and square), the left thumb draws the right thumb's shape and the other way round. Mirrored and parallel spells are unaffected. This changes what the scorer accepts, so it waits on Ray (open question 5); hide the toggle until then.

Accessibility: a sample dialogue line at the top shows the current text speed and size live.

• Text speed: Slow (25 characters a second), Normal (45, today's DialogueBox.CharactersPerSecond), Fast (90), Instant.
• Text size: A (Standard), A+ (×1.15), A++ (×1.3), applied to every screen through the theme's type scale. Layouts must hold at A++.
• High-contrast glyphs: glyph prompts, trails and the breath ring get a dark outline, a solid core with no glow fade and a thicker line. The colours still come from each spell's color.
• Reduced motion: no camera shake, no hit flash, no screen-wide pulses, toasts and screens cross-fade instead of sliding, and reward counters show their totals at once. It starts on when iOS Reduce Motion is on.

About: Credits (the credits half of today's Credits & licenses), Third-party notices, and the version and build number.

Third-party notices Open page

• Purpose: show the licences of what Velan ships with (Yarn Spinner, ANTLR, Protobuf, CsvHelper, Newtonsoft.Json and the rest of Data/Credits/notices.txt).
• In / out: from Settings → About; Back returns.
• Shows: a readable column (about 440 pt wide) with a heading per component, its licence and its text; a scrollbar.
• Actions: drag anywhere to scroll; Jump to opens a list of components.
• States: error: "The notices couldn't be read." (as CreditsView does today).
• Data: reads Data/Credits/notices.txt (and credits.txt for the Credits page).

In the field Open page

Field HUD

• Purpose: everything on screen while the player walks around a location.
• In / out: on arriving at a location. It hides during dialogue, field casts, battles and menus, and comes back after them.
• Shows:
  • Objective tracker (top-left): the tracked quest's title, its current stage and an arrow towards the stage's target. Tapping it opens the Journal on that quest.
  • Interaction prompt (top-centre): what the player is next to, as a verb and an object ("Open · Farmhouse door", "Talk · Aske", "To The Sallow Road"). Tapping it uses that thing. 48 pt tall, unlike today's 33 pt.
  • Map and Pause (top-right), 44 pt each.
  • Exit signs over exits in the world, as today.
  • Movement stick: appears where the left thumb lands in the left half (right half when left-handed) and goes when it lifts.
• Actions: tap the prompt; tap the tracker, Map or Pause; tap the world to walk to or use what was tapped (InteractionTaps); drag to move.
• States: no tracked quest: the tracker hides. Nothing nearby: the prompt hides. Busy (InteractionSystem busy): the prompt and taps are off.
• Data: reads the tracked quest and QuestLog, the interaction target (InteractionSystem), the location's exits.

Toasts

• Purpose: tell the player something changed without stopping play.
• Kinds: Quest updated (new quest, new stage, finished), Spell learned (with its glyph and colour), Item received (icon, name, count). Also small notices such as "You got away" after fleeing.
• In / out: they slide in at the top centre, under the prompt, stay 3 s (4 s at A++) and slide out. Tap to open what it's about (the Journal on that quest, the spell's detail, the item in the Inventory); swipe up to dismiss.
• Rules: one at a time; others queue. None appears during a cast, a dialogue choice or a battle; they wait. Toasts never pause the game.
• Data: listens to QuestLog.Changed, a spell-learned event and an item-received event (section 4).

Dialogue

• Purpose: people talking, and the player's choices.
• In / out: a Yarn node starts it (an interaction, a trigger, a cutscene); it ends when the node ends. It can open a Shop, a Field cast or a battle through commands.
• Shows: the box between the thumbs (x 202–642, 100 pt tall), the speaker's name and the typed line; a portrait standing on the box's left edge, rising into the stage; ▼ when the line is fully shown. Narration has no name and no portrait. Choices stack upward from the box on the right, first choice on top, 48 pt each, at most four; the box keeps showing the question. Log and Pause sit top-right.
• Actions: tap the box to finish the line, then to move on; tap a choice; Log shows the last 50 lines in a scrolling panel (paused).
• States: between lines during a cutscene command, the box hides (DialogueBox.Hide). No portrait for a speaker: the box shifts its text left and leaves no blank slot.
• Data: reads Yarn lines and options, the speaker's character data and portrait set, the line's mood tag, and the text speed and size settings.

Field-cast prompt

• Purpose: a spell drawn outside battle because the story asks for it: <<prompt_cast>> (cast it once) or <<learn_spell>> (trace it until learned).
• In / out: a dialogue command opens it; it closes 0.8 s after the cast or the last trace (FieldCast.DoneSeconds).
• Shows: the world dimmed with a vignette, so it's clear play has stopped; a panel top-centre ("Trace Coil" with pips ●●○ and "Trace both shapes. Breath is not timed.", or "Cast Repel" without pips); each thumb's glyph prompt in its drawing zone, at its true size, in the spell's colour.
• Actions: draw. Pause stays available. There is no Skip: these casts are part of the story.
• States: miss: the glyph shakes; after a few misses the bead slows and the strokes brighten (FieldCastRules). Done: "Coil learned" and the prompt fades.
• Data: reads the spell; writes the learned spell (and its toast) through GameData.

Shop

• Purpose: buy and sell with a shopkeeper (Halfway's market first, per VEL-61 and the Items and Economy tab).
• In / out: a dialogue command (<<open_shop halfway_odds_and_ends>>, the Items and Economy tab's command) opens it; Leave goes back to the dialogue or the field. It pauses the game.
• Shows: the shopkeeper's portrait, the shop's name and a line from them; Buy, Sell and Buy back tabs; the player's copper; a list of goods (name, short effect, price after the standing modifier on that Row, with the catalogue price struck through when it differs; sold-out items greyed; a commission shows its materials, such as "Mirror Grit 2/3"); the selected item's detail (icon, name, type, how many you have, effect); a quantity stepper; the Buy or Sell button with the total.
• Actions: pick an item, set the quantity, Buy or Sell. A sale over 50 copper, or selling the last of something, asks first (Confirm dialog).
• States: not enough copper: button disabled, "You need 6 more". Too many to carry: there is no bag limit; a stack past its cap is sold at once (Items and Economy), and the button says so ("Buy 3 · 1 sold on"). Nothing to sell: "Nothing you have is worth anything here." Key items never appear under Sell.
• Data: reads the shop's stock and prices (Data/Shops/<id>.json), the inventory, the purse and the player's standing (rep.evane on the Pale Row, rep.facets on the Amber Row); writes the inventory and the purse.

Menu Open page

Pause

• Purpose: stop play, and reach everything that isn't the world.
• In / out: the Pause button in the field (and in battle, open question 11); the app going to the background also opens it. Resume or ✕ closes it.
• Shows: "Paused", the location and the tracked objective; Resume; four tiles, Journal, Map, Spell book and Inventory; a Standing tile (section 11); Settings and Save and quit.
• Actions: each opens its screen. The four tiles open the tabbed menu on that tab.
• Data: GameShell.Pause and Resume.

Save and quit

• Purpose: leave to the title without losing progress.
• In / out: from Pause. Cancel returns to Pause; Save and quit saves, fades and opens the Title.
• Shows: "Save and quit to the title?" and where the player will pick up.
• States: saving: the buttons give way to "Saving…" and a spinner. Save failed: "Couldn't save. Your last save is from 2 min ago." with Try again, Quit anyway and Cancel. Today GameShell.QuitToTitle saves and leaves even if the write fails, so it needs to report the result.
• Data: GameShell.Save and QuitToTitle.

Journal

• Purpose: what the player is doing and has done.
• In / out: Pause → Journal, the objective tracker, or a quest toast. Back returns; ✕ resumes play.
• Shows: the menu tab bar; Active and Finished tabs with counts; a list of quests (★ for the main quest, then side quests; the tracked one marked) with category and place; the selected quest's title, category, place and giver, its description, and its stages: reached ones ticked, the current one bold, later ones hidden.
• Actions: select a quest; Track (one at a time; the main quest is tracked by default); On map opens the Map at the current stage's target.
• States: empty: "No quests yet." (Active) and "Nothing finished yet." (Finished). A stage with no target hides On map.
• Data: reads QuestCatalog and QuestLog (title, description, stages, status), the tracked quest; writes the tracked quest.

Map

• Purpose: where the player is, and where to go.
• In / out: Pause → Map, the Map button (opens Local), or On map in the Journal. A Local and World switch sits top-left.
• Local map: a top-down image of the current location, north up, centred on the player (▲ shows facing). Markers: exits (→ and where they lead), the tracked quest's target (◆), shops, people who matter. Tap a marker for its card (top-right). Centre returns to the player.
• World map: the world map art with every discovered place and the routes between them. Visited places are filled, known but unvisited are hollow, undiscovered ones are hidden. Tap a place for its card: name, subtitle, visited or not, and the quests there.
• Actions: pinch to zoom, drag to pan, tap markers.
• States: no local map for this location yet: Local is disabled and World opens. Loading the image: a placeholder and a spinner.
• Data: reads the world map data and flags, the location's local map image, bounds and markers, the player's position and facing, and the tracked quest's target (section 4). Fast travel is open question 6; nothing in this spec assumes it.

Spell book

• Purpose: every spell the player knows, can learn, or has heard of.
• In / out: Pause → Spell book, or a spell toast. Back returns.
• Shows: filter chips (All, Evane, Facets, Composites, then one per Evane faction once the player knows two of its spells) and a count ("4 of 27 spells learned · 2 threads"); a grid of cards: glyph icon, name in the spell's colour, drawing style and effect. Unlearned spells have a dashed outline and "Not learned yet"; unknown ones read "? Unknown glyph · Find its fragment". A split glyph with one half held shows that half and "Half found" (Facet Seal in Act 2, Prism Snare and Pavilion Wake in Act 3). A sealed spell shows a pale blue seal over its card and "Your hands have forgotten it". Threads follow as their own section, named and with their parts ("Headwind · Repel into Gale").
• Actions: tap a card for its detail; filter.
• States: empty can't happen (Repel starts learned), but a filter can be empty: "No Facet spells learned yet."
• Data: reads the spell catalog, IKnownSpells and the composite recipes (SpellBookContents), and the unknown list (section 4).

Spell detail

• Purpose: how to draw one spell, and what it does.
• In / out: from the Spell book; Back returns; Practice (or Learn) opens Practice.
• Shows: the name in its colour; side, drawing style, size and breath window; the effect; how to draw it in words (the spell's description); a lore line. Each thumb's stroke in its own panel, drawing itself at the template's pace with a dot where it starts (as StrokeAnimation does today). For a composite, the two parts one after the other.
• Actions: Practice (Learn when not learned), Replay.
• Data: reads the spell and whether it is learned.

Spell practice and learning

• Purpose: draw a spell with nothing at stake: to learn it, or to get better at it.
• In / out: Practice or Learn on Spell detail; Done returns there.
• Shows: a quiet backdrop (no world, no enemy); a panel top-centre with the spell and, after each cast, its quality word, score, power multiplier and breath used, and the breakdown (shape, size, pace, corners, sync) that the battle HUD shows today; the breath ring; the glyph guides in each drawing zone.
• Actions: draw; Guide on or off (the glyph prompt); Breath on or off (timed like a battle, or untimed).
• Learning: the same frame, with pips (●●○) and "Trace both shapes. Breath is not timed." instead of the last score, as in the field cast. Learning here, outside battle, is new: today only the battle's spell panel teaches.
• States: fizzle: the reason ("Not learned", "Breath ran out", "Shape too far off", "Your hands have forgotten …" for a sealed spell, "Your hands won't answer …" for one an enemy has bound) in place of the score. Split glyph: learning shows each half's fragment image over its own thumb.
• Data: reads the spell and the scoring config; learning writes the learned spell and raises its toast.

Inventory and item detail

• Purpose: what the player carries, and what each thing is.
• In / out: Pause → Inventory, or an item toast. Back returns.
• Shows: the tab bar; category chips (All, Consumables, Gear, Materials, Key items, the Items and Economy tab's four categories); the purse in copper; a grid of 64 pt slots with stack counts; the selected item's detail on the right: icon, name, type, flavour line, effect, and its actions.
• Actions: select; Use (consumables), Equip or Remove (gear), Read (letters and documents, which opens Letters and documents); Trace (a glyph fragment, which opens Spell practice and learning). Key items can't be dropped or sold.
• States: empty bag: "Nothing in your bag yet." Item can't be used here: Use disabled with the reason ("Before a battle", "At a fragment": the Items and Economy tab's uses).
• Data: reads and writes the inventory and equipped gear (VEL-61's save model); reads item definitions.

Letters and documents

• Purpose: read letters, notes and documents, starting with Aske's two letters (pale blue seal for Twinhold, amber for Lanternfall).
• In / out: Read in the Inventory, or a document found in the world. ✕ returns.
• Shows: a page on a dark backdrop, its seal, the addressee, the text and the signature; ‹ › to turn pages and "Page 1 of 2".
• Actions: turn pages (tap ‹ › or swipe); close.
• Actions when sealed: Break the seal, behind a Confirm dialog ("Aske said not to."), as the Items and Economy tab specifies.
• States: sealed: only the front, the addressee and the seal. Text missing: "The ink has run." and a logged error.
• Data: reads the document; writes its opened flag (letter.twinhold.opened, letter.lanternfall.opened).

Battle Open page

Battle HUD

• Purpose: what the player needs while fighting, and nothing in the drawing zones.
• In / out: a battle pushed over the location (SceneFlow.StartBattle), or Practice battle from the Title. Out to Results.
• Shows:
  • Player (top-left): name, health and shield bars.
  • Enemy (top-centre): name, health bar, attack wind-up bar and "attacks in 2.4 s"; later its status (staggered, shielded) as icons.
  • Last cast (under the player panel): spell, quality word and score, and the damage sum. The full breakdown moves to Practice.
  • Spells and Pause (top-right), 44 pt each; Flee under the player panel when the encounter allows it (AllowFlee).
  • Breath ring in the upper middle (StrokeView, 58% of the way up the screen), combat numbers by the enemy, the hint "Draw a spell with both thumbs at once" until the first cast.
• Actions: draw; Spells opens the spell panel (pauses; tap a spell to learn it, as today); Pause; Flee.
• States: learning (from the spell panel): the panel from the field cast replaces the last-cast chip. Practice battle: Flee is "Title".
• Variants the walkthroughs need: a plated or shielded enemy shows its shield as a second bar that empties on a stagger (the Sallow Wyrm, Act 1); a wagon health bar under the enemy panel (the Long Road defence, Act 2); a storm timer in place of the enemy's wind-up (the glass storm, Act 2); a fight timer (the colossus's Pull, Act 3); the Pane gauge, a bar from Still to Shattered across the top of the stage, and an ally bar for the chorus when the player fights beside it (Act 4). Each sits in the upper middle band, never in the drawing zones.
• Data: reads BattleState, the encounter request and the cast results. Tune and the debug panel are development builds only.

Battle results: victory

• Purpose: close the fight and show what it earned.
• In / out: the enemy is defeated; Continue ends the battle and returns to the location (SceneFlow.EndBattle).
• Shows: "Victory", the enemy and a line of stats (casts, fizzles, time, best cast); reward tiles (XP with level progress, then materials and items); a level bar. Battles never pay copper (Items and Economy); a human who yields may leave a valuable.
• States: level up: a banner over the XP tile. Rewards count up one after another; a tap shows them all; Reduced motion shows them at once. No rewards (a sparring match): the stats and Continue only.
• Data: reads the encounter's XP and drops; writes them to the profile and inventory (Encounters adds XP today).

Battle results: defeat

• Purpose: let the player try again, and give them a way to do better.
• In / out: the player's health reaches zero. Try again restarts the battle; the second button returns to the location.
• Shows: "Defeated", a line about the enemy, stats, and a tip for this enemy.
• Actions: Try again; Back to Sallowbank (the location, or what defeat leads to: open question 9).
• States: can't lose (CanLose false, story fights): only Try again. Fled: no panel; the player is back in the location with a "You got away" toast.
• Data: reads the encounter request and the enemy's tips.

Shared Open page

Loading and location transitions

• Purpose: hide scene loads, and tell the player where they've arrived.
• In / out: any SceneFlow transition: entering a location, Continue, New game, a battle starting and ending, quitting to the title.
• Shows: the fade (as today) for quick loads. When a load takes over 0.5 s, a card: the location's art, its name and subtitle, a spinner and a tip between the thumbs. On a first visit, the name card holds for 1.5 s on arrival. Battles use a faster, more dramatic transition (VEL-80).
• Actions: none; taps do nothing.
• States: load failed: back to the previous location, or to the Title if there is none, with "Couldn't load that place." (SceneFlow refuses and logs today).
• Data: reads the location's title, subtitle and art, and the tips list.

Confirm dialog

• Purpose: one pattern for every action that can't be undone: replacing a save, quitting, selling, breaking a seal, paying the unbinder.
• Anatomy: a scrim over the screen it came from; a panel in the upper middle with the title as a question, one line saying what happens, and two buttons, Cancel on the left and the action on the right, named for what it does ("Sell 3", "Start over", never "OK"). Destructive actions have a heavy outline. Tapping the scrim cancels.
• States: working: both buttons disable and the action shows a spinner. Failed: the panel says what went wrong and offers Try again.
• Data: none of its own; the caller supplies the strings and the action.

Screens the walkthroughs add Open page

The four act walkthroughs and the side-quests tab use a few screens this spec didn't have. They follow the layout rules in section 1. None has a wireframe yet.

Standing

• Purpose: where the player stands with each side, each Evane faction and themselves. The walkthroughs call it the reputation panel (Act 2) and the profile (Act 3).
• In / out: the Standing tile on Pause; a one-time summary at the end of Act 2 (Act 2 scene 5.6). Back returns.
• Shows: two side bars, Evane and Facets, from −100 to 100, each with its band name (Trusted from 25, Neutral, Distrusted from −25, Shunned from −60) and what the band does (prices on that Row, which gates open). Below them, a row for each Evane faction the player has met (Wardens, Tenders, Keepers, Still Choir, Waymakers). Morality as a band word, never a number (Clean, Wary, Fallen, Dark, the depths), and, when the player is Wary or worse, the way back as a count ("2 more good deeds to Wary", Act 3's long_way_up). Titles earned, such as Even-handed (Act 4).
• States: before Act 2: the two side bars only. Fallen: the morality row is drawn in the Undermere's colours and names the gates that are shut.
• Data: reads rep.evane, rep.facets, rep.wardens, rep.tenders, rep.keepers, rep.choir, rep.waymakers, morality, atonement.deeds and the bands in the walkthroughs' continuity notes (Act 4, "Continuity notes").

Notice boards

• Purpose: one screen for every board of work or goods: the Truce Board and the Market Board in Halfway (Act 1), the bulletin boards in Twinhold and Lanternfall (Act 2), Dace's caravan board on the Long Road (Act 2) and the Proving Ring's Ring Card (Act 1). It answers open question 8: the Market is a board, not a second Shop.
• In / out: tapping a board in the world ("Read"). Leave returns to the field.
• Shows: the board's name and who keeps it; a list of notices, each with a title, the giver, the place, the pay in copper (or "standing" for the Ring), and which side posted it (a pale blue or amber pin, plain for Halfway). The Market Board lists goods instead: item, count, price and seller, with Buy. The Ring Card lists the ladder: the player's place, the next challenger and their rank.
• Actions: Take a job (it joins the Journal as a side quest), Leave it; on the Market Board, Buy (through the Shop's purchase panel); on the Ring Card, Challenge.
• States: nothing posted: "Nothing today. Come back tomorrow." Board refuses you (Shunned with the side that keeps it): the notices show, Take is disabled, "They won't take your work."
• Data: reads the side quests whose board field names this board (side-quests tab), the Market Board's daily consignments (Items and Economy), the ladder flags (ring.rank, side-quests tab).

Cutscene

• Purpose: story moments the player watches: Rook's one-handed seal in the Ring (Act 1), the reflections in Corran's glass, the Hundred-Year Hour and the Unstilling (Act 3), the arrival at the Pane's rim (Act 4).
• In / out: a Yarn command starts it and the node's end closes it.
• Shows: letterbox bars top and bottom; no HUD; the Dialogue box sits on the lower bar; the camera follows <<camera>> markers.
• Actions: tap to advance lines; hold Skip (top-right, after the first viewing only) to jump to the next choice or the end.
• Data: the Yarn node and its camera markers.

Measuring card

• Purpose: show the player how the Twinhold Measuring read their hands (Act 2 scene 1.2).
• Shows: five bars, one per Evane faction, scored from the player's three drawings (corners, pace on curves, evenness, size and slowness, thumb sync), and which court leads (court.lead). A line under it if a Facet spell was drawn ("measured, not cast").
• Actions: Continue.
• Data: the Measuring's three cast results; writes court.lead.

Epilogue cards

• Purpose: close Act 4 (scene 4.19): six illustrated cards, one each for the Pane, Sallowbank, Twinhold, Lanternfall, the companions and the antagonists, chosen by act4.outcome, then a black screen with one line, then the "The world goes on" title card.
• Actions: tap to turn a card; no skip the first time.
• Data: act4.outcome, the companions' trust and step-out flags.

Variants of existing screens

• Dialogue, signed lines: Still Choir speakers sign; their lines show small mirrored hand-sign icons above the text (Act 2, Hushfold).
• Field-cast prompt for a thread: both parts' guides one after the other in each thumb's zone, joined by a dotted line (Headwind in Act 2, Thaw in Act 3, the First Pair in Act 4). <<prompt_cast>> takes a thread id.
• Field-cast prompt for a split glyph: each half's fragment image over its own thumb (Facet Seal, Prism Snare, Pavilion Wake).
• Map, travel: Act 2 adds Long Road stops the player can travel between. That needs a Travel button on a visited place's card, which is open question 6.
• Toasts, item received: the walkthroughs' "item received notice" is the Item received toast.

Walkthrough screen names Open page

The walkthroughs name screens as the game names them today, or loosely. Every name they use maps to a screen in this spec:

Open questions for Ray Open page

1. Name entry. Free text with the keyboard (and a word filter), or chosen from a list? Is there a default name, and can the player rename later?
2. Body type labels. Keep "Male" and "Female" on the cards, or neutral labels ("Body 1", "Body 2") with pronouns chosen separately?
3. Save slots. One autosaved slot, as built, or several slots, or a manual save as well?
4. Practice battle on the title. Keep it for players (a golem to spar with), or make it development-only now that Practice exists in the spell book?
5. Left-handed mirroring. May a player swap which thumb draws which shape in asymmetric spells (Facet Seal, Bevel Lash, Prism Snare)? It changes scoring, and it matters for the tournaments (Codex section 10).
6. Map. Is there fast travel between visited places? Is the world map fogged until explored, or drawn in full with places hidden? Local maps for towns only, or for every location?
7. Toasts. Tap-through to the related screen (as specced), or passive only?
8. Market. Is the Halfway Market (Codex section 9: trading between players) its own screen beyond this Shop? VEL-63 specs it as a Notice board (section 11), which reuses the Shop's purchase panel.
9. Defeat. What does losing cost: copper, back to the last save, waking at an inn or with Aske?
10. Cast feedback. Should players see the full score breakdown (shape, size, pace, corners, sync), or only the quality word in battle and the breakdown in Practice (as specced)?
11. Pausing battles. Can a battle be paused (as specced: Pause top-right), given the breath timer and future tournaments?
12. Quest status. Can quests fail or be missed? The journal has no Failed tab because QuestStatus has no such state.
13. Haptics. On or off only, or a strength setting too?
14. Items in battle. Can consumables be used in battle? That needs an item button on the battle HUD, which is already crowded at the top.
15. Sealed letters. Can the player break the seals on Aske's letters? It could be a moral choice ("Believe neither until you've met both"), and it decides whether the viewer has a sealed state. The Items and Economy tab and Act 2 already assume yes, behind a warning, and this spec now follows them (VEL-63).