.ink support for investigation segments

[ViMaSter]

Description

Check the discussion linked below.

Acceptance Criteria

This story will be finished when

• a main menu for investigation exists
  • Examine allows the user to point-and-click on the background and placed details to start a linear dialogue
    • already examined details are highlighted
  • Talk allows the user to start a linear dialogue based on a list of choices
    • already selected options are highlighted
  • Move allows the user to move between scenes based on a list of choices
  • Present allows the user to present evidence
  • all 4 options can unlock additional Talk and Move choices

Discussed in #441

^{Originally posted by ViMaSter August 11, 2024}
More public notes than call-to-action, but wrote down some thoughts about a potential implementation of investigation sections.
Written down just to hear other input though, nothing's set in stone!

---

Reference UI

---

Ink script could look something like…

&SCENE:Kitchen
&ACTOR:Dan
&MODE:Investigation
&ADD_FAILURE_SCRIPT:IRRELEVANT_EVIDENCE
+ [Arin being in the Kitchen]
    …dialogue…
    &UNLOCK_MOVE_CHOICE:Waitrose LA branch
    …dialogue…
+ [LOCKED:Waitrose LA branch]
    …dialogue…
+ [Plumber_Invoice]
    …dialogue related to presented evidence…

Which would…

• load the Kitchen to the BGSceneList
• show Dan in the center (optional; if not added, only the room is shown)
• open the investigation menu (Examine, Move, Talk, Present)

Examine

• UI and actor are hidden and the player can click through the scene; the scene is also populated with Details
• like our Actor components, we also have GameObjects that have a new Component in scene prefabs: Detail
  • Detail takes a DetailData object containing properties:
    • 2D sprite
    • IsPickup (bool):
      • true: renderer and collider are disabled after first examination
      • false: remaining in the scene
    • .ink script that plays when examining it (which can either just play a dialogue or add evidence as before)
  • Detail has a SpriteRenderer and pixel-perfect collider so the player can "examine" it
  • after examining a detail, the NarrativeScriptPlayer stores $SCENENAME_$DETAILNAME (like Kitchen_Post) in List<string> examinedDetails and changes the cursor to indicate that this Detail was already examined (to indicate progression to the player)
    • NarrativeScriptPlayer instead of the Detail, as that state needs to be retained when Moveing between scenes

Move

• allows moving to locations unlocked by &UNLOCK_SCENE
• has a Back button

Talk

• presents all + […] options that don't match evidence names; similarly to existing Choice sections
• NarrativeScriptPlayer tracks List<string> examinedChoices and adds $SCENENAME_$CHOICETITLE (like Kitchen_Arin being in the Kitchen) after selecting, to add a ✅ next to already read choices (to indicate progression to the player)
• Hides options prefixed with LOCKED: at first and only shows them after being unlocked by &UNLOCK_CHOICE
• tagging a choice as #Initial
  • immediately play this choice when the user selects Talk for the first time and for the first time only
  • if no #Initial choice is present or after the #Initial choice was played once, Talk will jump to the choices directly, with no dialogue in between
• has a Back button

Present

• identical to the existing ability to present evidence:
  • if a branch for that piece of evidence exists: play it
  • if not: fall back to ADD_FAILURE_SCRIPT entries

---

Considerations:

Why split out Detail from Evidence?

I think our current Evidence/Actor system is really robust in it's current form. This way, rather than changing it, we build on top: If a Detail adds Evidence to the court record, we can just do so in the .ink script associated with the DetailData.
Additionally not all details relate to evidence; writers want the ability to add details to a scene a player can interact with for optional dialogue that doesn't relate to game progress.

Should we add a prefix to clearly separate Talk and Present options?

No real reasoning here, just decided not to. I don't expect us to run into conflicts where we want to show a Talk option that shares the name with existing Evidence data.
Happy to change it, if something like this feels more natural though:

&SCENE:Kitchen
&MODE:Investigation
&ADD_FAILURE_SCRIPT:IRRELEVANT_EVIDENCE
+ [TALK:Arin being in the Kitchen]
    …dialogue…
    &UNLOCK_CHOICE:Waitrose LA branch
    …dialogue…
+ [TALK:Who bought the groceries?]
    …dialogue…
    &UNLOCK_SCENE:Waitrose
    …dialogue…
+ [LOCKED:Waitrose LA branch]
    …dialogue…
+ [PRESENT:Plumber_Invoice]
    …dialogue related to presented evidence…

[ViMaSter]

Parts of this feature were implemented in the PRs mentioned below this comment.

Work left

Talk button

• make both Esc and the button a player bound to Back go back from the sub-menu

Move button

• make both Esc and the button a player bound to Back go back from the sub-menu

Refactor the current implementation:

• no longer find GameObjects by name, rather use (an existing or new?) Component that provides access to that info
  (notes: Support for Talk and Move inside investigation sections #460 (comment))
  (notes: Support for Talk and Move inside investigation sections #460 (comment))
• render foregrounds on top of backgrounds in the preview image
• add mouse test coverage (keyboard already covered)
  (notes: Support for Talk and Move inside investigation sections #460 (comment))