SOFTENG 206 has a semester-long project. You will start working on your project from day 1 and gradually build it throughout the semester.

The project constraints will be released one milestone at a time. This page contains the constraints for the individual Alpha version.

• Meet the Clients
• Introducing the Product: TimeMystery
  • Project Starter Code
  • Selecting a Theme
• Alpha version (individual)
• Beta version (group)
• Final product (group)

Introducing the Product: TimeMystery

You will develop TimeMystery, an interactive time-travel mystery game/simulation for Insight Investigations’ training programme. The player takes on the role of a trainee investigator who travels between different epochs, speaks with an LLM-powered non-player character (NPC) who appears in both epochs, and interacts with the GUI to gather evidence. The player then chooses from a set of predefined interventions to alter the timeline and discovers whether the chosen intervention produces the best outcome. Alpha introduces this core experience with two epochs and four interventions. Later releases will expand it with additional features and polish, informed in part by the clients’ feedback.

In this brief, the NPC’s two appearances are called the earlier-epoch NPC and the later-epoch NPC. They are two versions of the same fictional person, not separate characters.

For this project, assume a single, changeable timeline: altering the past changes the present and the future, as in Back to the Future and X-Men: Days of Future Past. Do not use a branching-timeline model, as in Avengers: Endgame, where changing the past creates an alternative timeline. Likewise, do not use a closed-loop model, as in Harry Potter and the Prisoner of Azkaban, where travelling to the past fulfils events that have already happened.

The player should understand what caused the problem and decide which intervention in an earlier epoch will produce the best outcome.

Your setting is open. Your game could take place in space, a medieval world, an alien civilisation, a fictional version of the present day, or another appropriate fictional setting. The jumps between epochs could span minutes, years, decades, or longer.

In this brief, must and must not identify fixed, assessed constraints. Should identifies a recommendation that may improve the application but is not an assessed constraint. Everything else is deliberately open for you to design and, where useful, discuss with the client. Client conversations can help you explore alternatives, test your ideas, and identify the option that best meets the client’s needs. There is not necessarily one correct design; the final design decisions are yours.

Project Starter Code

For an explanation of the project starter code, please refer to the Project Starter Code page. The starter provides the reusable JavaFX/LLM API foundation, an asynchronous-call example, the State pattern, and examples of loading prompts and YAML data. It also provides a very basic game that is similar in spirit—chatting with an LLM-powered NPC to solve a mystery—but different at its core.

For Alpha, you must design and implement the TimeMystery-specific functionality, including navigation between the two epochs, the prompts for both versions of the NPC, the GUI interactable, the investigation and selection timers, and all four interventions and outcomes.

Selecting a Theme

Alpha Version

For Alpha, you need to develop a small version of the game within the following constraints. You will complete Alpha individually. After Alpha, you will work in teams of three students for the Beta and Final releases. Your team may continue with the theme or story created by one member, or it may start again with a completely new idea. Therefore, you should not invest time in polishing the GUI or application. Alpha is a prototype for showing the client what could be achieved.

Game Objective

Alpha is divided into two timed phases: investigation and intervention selection. During the investigation, the player gathers information across two epochs. The player then selects an intervention and observes its outcome. The detailed assessed constraints are listed below.

Game Elements

• Two epochs: The game must contain two distinct points in its timeline.
• One recurring NPC: The same fictional, LLM-powered NPC must appear in both epochs.
• Time traveller: The player must be able to visit the two epochs in either order and travel between them as many times as they choose during the investigation. How time travel is represented and controlled in the GUI is a design choice.
• Conversation memory: The player must be able to chat with both versions of the NPC, and each version must remember its own conversation with the player. Once the player has spoken with the earlier-epoch NPC, the later-epoch NPC must have access to that conversation on the player’s next visit. The earlier-epoch NPC must not have access to conversations from the later epoch.
• GUI interactable: At least one relevant GUI interactable must be available in the earlier epoch. What counts as a GUI interactable will be discussed during client meetings.
• Bounded final choice: After investigating, the application must present exactly four concrete interventions. Each intervention must describe an action applied to the earlier epoch and have a pre-authored consequence for the later epoch. Exactly one intervention must fully resolve the original problem. Where and how the four options are displayed is a design choice.

Scenario Design

• Your two epochs must be part of the same coherent scenario.
• The NPC must be recognisable as the same person in both epochs. The NPC’s backstory and the communication style of each version are design choices.
• Each version of the NPC must have an epoch-appropriate knowledge boundary and memory boundary. The earlier-epoch NPC must not know events that have not yet occurred from its perspective.
• The story, setting, identity of the person, and size of the time jump are your design decisions (minutes, hours, days, years, decades, or more).
• Whether the earlier-epoch and later-epoch NPC appear in the same location at different times or in different locations is a design choice.
• The mystery should be small enough to investigate within the time limit.

Conversation Mechanics

• Conversations must be generated programmatically using the provided LLM API based on what the player asks.
• The prompt for each version of the NPC must define its identity, circumstances, and knowledge boundary. These internal prompts must not be displayed in the player-facing GUI, they are sent to the LLM alongside the player’s conversation.
• Each version should behave consistently with the information defined in its prompt.
• Responses should be concise enough for the player to complete the investigation within the time limit.
• You will achieve this behaviour through appropriate prompt engineering, which will be covered in class.

State Between Playthroughs

• Each new playthrough must begin from a clean state. Conversation histories, collected information, interactable state, timers, intervention selections, and outcomes from previous playthroughs must not carry over.
• Conversation memory must persist only within the current playthrough. During that playthrough, the later-epoch NPC must still remember the player’s conversation with the earlier-epoch NPC.
• The application is not required to provide an in-app replay option. However, if one is provided, it must reset the game completely.

Time Limit

• The investigation must last two minutes, and the application must allow the player to end it early. These two minutes must include any information presented before the investigation begins. Introductory information should not reveal too much: discovering what is happening is part of the game.
• When the investigation ends, the application must prevent the player from travelling, conversing, using interactables, or collecting information.
• Exactly four possible interventions must then be revealed for the first time. The player must have 30 seconds to select one.
• The application must allow early submission. When time expires, the current selection must be submitted automatically. If there is no selection, the game must end.
• The intervention timer must end when the player submits a choice or the 30 seconds expire. Presentation of the outcome is not timed (but should be short).
• After the player submits an intervention, the application must present its pre-authored consequence in the later epoch and make clear whether the original problem was resolved. How this outcome is presented is an open design choice. The outcome should be brief and simple, and you should not spend significant development time creating an elaborate presentation.

Other Constraints

• The GUI must never freeze; API communication must not block the JavaFX application thread.
• The interface should make the remaining time clear to the player.
• All player interaction and feedback must occur through the GUI. Debug logging may appear in the console, but the player must not need the console to interact with the game or receive feedback.
• For Alpha, functionality and usability are more important than graphic design.
• The chat window must be integrated into the scene where the conversation takes place, rather than appearing in a separate window.
• The application must include some text-to-speech functionality, but it should use it selectively rather than automatically reading every generated response aloud. Essential information should not be available only through audio.

Good luck!

Beta Version

Beta Version

Beta expands the individual Alpha prototype into the complete team version of TimeMystery. Your team will develop one coherent time-travel investigation containing three epochs, three temporal versions of the same fictional person (NPC), three physical epoch rooms, and a final intervention supported by a written rationale.

In this brief, must and must not identify fixed, assessed constraints. Statements using should are recommendations intended to improve the client experience, but they are not independently assessed as compulsory functionality.

Scenario Design

• The game must contain exactly three distinct epochs: Epoch 1, Epoch 2 and Epoch 3. Epoch 1 is before Epoch 2, Epoch 2 is before Epoch 3.
• The game must contain exactly three NPCs (no more chattable NPCs). They must be three temporal versions of the same fictional person (not three different people) with exactly one version in each epoch.
• The three temporal versions must be the game’s only NPCs. The game must not contain additional conversational, interactive or LLM-powered characters.
• Non-interactive people may appear incidentally in background artwork, but they must not function as characters
• The main mystery must concern a problem that is observable in Epoch 3.
• The problem must have developed or been triggered between Epoch 2 and Epoch 3, while evidence from all three epochs should be needed to understand its cause.
• The final intervention must be applied in Epoch 1 or Epoch 2 and must have a predetermined consequence in Epoch 3.
• The three epochs, temporal versions, rooms, conversations, interactables, clues and temporal consequences must contribute to the same coherent mystery.
• The scenario must be realistically investigable within five minutes without exhaustive questioning, repeated puzzle attempts, or knowledge not presented by the application.
• The gameplay must remain consistent between runs.
• Your setting, atmosphere, the recurring person’s identity and circumstances, the lengths of the time jumps, and the nature of the mystery remain your team’s design decisions.

Time-Travel Mechanism

• The player must be able to travel among all three epochs during the investigation and revisit them in any order.
• Similar to Alpha, later epochs NPCs must remember the past conversations. For beta, they need to also must be aware if the player interacted with the interactable in their current and previous epoch.

Verdict

• The player must have asked at least one question of each of the three temporal versions and found/interacted with all three core interactables. If these conditions have not been met when the investigation timer ends, the application must show an incomplete-round screen with a replay option instead of asking for an intervention. If the conditions are not met, must not possible trigger the early intervention.
• The four possible interventions must remain hidden during the investigation.
• After the investigation ends, the application must reveal exactly four concise interventions for the first time.
• Each intervention must describe a concrete action that could be performed in Epoch 1 or Epoch 2 to affect Epoch 3. The options must not explicitly reveal the underlying diagnosis.
• Exactly one intervention must be correct.
• The player must select one of the four interventions.
• When selecting an intervention, the player must provide a free-text rationale that:
  • identifies the underlying problem or cause;
  • cites relevant evidence discovered during the game;
  • explains how the selected intervention is intended to affect Epoch 3.
• Your Java code must determine whether the selected intervention is correct and must apply its predetermined temporal consequence.
• A separate LLM call (maybe with high reasoning) must evaluate whether the rationale written by the player contains a correct diagnosis, uses supporting evidence discovered during the game, and gives a coherent explanation of the selected intervention’s intended effect.
• Unsupported claims, fabricated evidence, and evidence not discovered during the current run must not count as supporting evidence.
• The application must distinguish the following four verdicts:
  • a correct intervention with a correct, supported and coherent rationale;
  • a correct intervention with an incorrect, unsupported or incoherent rationale;
  • an incorrect intervention with a correct, supported and coherent rationale; and
  • an incorrect intervention with an incorrect, unsupported or incoherent rationale.
• Each intervention must have its own short, pre-authored temporal consequence selected deterministically by Java rather than generated by an LLM.
• Each consequence must identify the intervention, explain its effect in Epoch 3, and state whether the original problem was resolved.
• The verdict screen must remain visible until the player chooses to continue.

Time Limit

• The application must begin with an untimed briefing.
• The briefing must explain the initial situation, investigation objective, time-travel controls, and how interactable objects are indicated.
• The briefing must not reveal the four interventions.
• The investigation timer must begin only when the player explicitly starts the investigation and the investigation controls become available.
• The investigation must last five minutes, and the application must allow the player to finish early.
• The timer must remain visible in every epoch, including while the player is chatting with an NPC or waiting for an LLM response.
• The investigation timer must continue while an LLM request is pending.
• At investigation expiry or early completion, the player must no longer be able to travel, converse, use interactables, or collect evidence.
• An LLM reply arriving after the investigation ends must be ignored and must not discover evidence or alter timeline state.
• After a complete investigation, the player must have thirty seconds to compare and select one of the four interventions.
• The application must allow early selection. Submitting early must lock the intervention and begin the rationale period.
• At selection expiry, an existing selection must be submitted automatically.
• If no intervention is selected, the application must show an incomplete-round screen with a replay option and must not produce an intervention outcome or rationale evaluation.
• The player must have sixty seconds to write the rationale, and the application must allow early submission.
• At rationale expiry, non-blank text must be submitted automatically.
• A blank rationale must not trigger an evaluator call. The application must use a standard unsupported-rationale result and feedback.
• Waiting for the rationale evaluator and reading the final verdict must be untimed.

Epoch Rooms and Interactables

• Each epoch must be represented as a physical room or another explorable physical place associated with that point in the timeline.
• There must be a dedicate JavaFx scene wher the player can choose which timeline to visit (similar to the coffee shop template) separated from the three epochs.
• An epoch must not be represented only by a menu, a chat-only screen, an abstract form, or a collection of generic buttons.
• Each of the three epoch scenes must contain the following as parts of one coherent interface:
  • a visible figure or other clear visual representation of that epoch’s temporal version of the recurring person;
  • the physical room or place that the player can inspect for information (find interactable);
  • one required core GUI interactable; and
  • the integrated chat used to converse with the temporal version.
• The NPC figure, relevant room content and chat must remain visible together while the player is conversing.
• The chat may be positioned on the left, right or bottom, or in another clearly allocated area of the scene. It must not float over, cover or make inaccessible the NPC, the core interactable, or relevant parts of the room.
• A separate chat window, a modal dialogue that replaces the room, or a chat-only scene must not be used.

For this project, a core GUI interactable is a visually represented object or control situated within an epoch’s room that the player directly manipulates through the GUI to obtain evidence, change Java-owned state, or interpret the effect of an earlier action. Opening, moving, dragging, arranging, adjusting, assembling, comparing, selecting part of, or operating an object are possible forms of interaction.

• The NPC, chat box, travel control, timer, navigation controls and final intervention controls must not count as core interactables.
• A generic button labelled “clue”, “reveal evidence”, or similar that only displays pre-authored text must not, by itself, count as a core interactable.
• A core interactable must be meaningfully situated in its room and connected to the mystery.
• The application must contain exactly three interactables, one in each epoch.
• Each core interactable must be visually apparent or explicitly indicated without requiring the player to click randomly.
• Using a core interactable must produce immediate visible feedback.
  

Persona Engineering

• The three NPCs must remain recognisable as the same fictional person at different points in their life.
• Each temporal version must use a distinct epoch-specific prompt.
• The versions must share a coherent identity and backstory while differing appropriately in their circumstances, knowledge boundary, memory boundary, behaviour and communication style.
• An earlier version must not know events that have not yet occurred from its perspective.
• Each version must remember its own conversation with the player during the current run.
• Java must pass relevant earlier timeline state and discovered evidence to later temporal versions.
• A later version must not display an earlier version’s raw conversation as though it were its own chat history.
• Each temporal version must know enough about its part of the mystery to provide meaningful information rather than only generic or evasive responses.
• Each temporal version must respond consistently to relevant actions the player has performed in its room
• LLM responses must remain concise enough for the player to complete the investigation within five minutes.

Game Design

• The application must be smooth and responsive. API communication must not block the JavaFX Application Thread.
• The application must visibly acknowledge when an LLM request is pending.
• A failed or malformed persona response must not freeze or crash the application, discover evidence, or alter timeline state.
• While the relevant stage remains open, a failed request must produce a visible recoverable error and allow the player to retry.
• When rationale evaluation fails, the application must preserve the player’s rationale, display the Java-controlled intervention consequence, identify the evaluation as unavailable, and allow a retry.
• Replies associated with an expired stage or previous run must be ignored and must not alter the current interface, evidence, or timeline state.
• All player interaction and feedback must occur through the GUI rather than the terminal or console.
• The latest chat content should remain visible without requiring the player to scroll manually.
• Pressing Enter should send a chat message when the chat input has focus. The application should provide another visible way to send the message as well.
• The application must allow the player to replay without restarting it.
• Replay must reset the timeline, conversations, evidence records, interactables, timers, stage, selected intervention, rationale, evaluation and verdict.
• Text-to-speech is optional for Beta. If used, it must short and pre-cached (otherwise too much delay if generated on the fly)
• Automatically speaking every generated LLM response must be avoided because the audio may be slower than the player can read.
• Sounds and music are optional. If used, they should not be loud, invasive, and shuld be able to mute.

General Feedback from Alpha

The clients made the following recurring observations while playing the Alpha applications. These are general suggestions, not additional compulsory requirements. They are provided to help your team improve the Beta experience.

• The window size should not change when navigating scenes.
• Interactable objects should be visually apparent. Avoid making the player click randomly to discover what can be used.
• Keep the story and root problem small enough to understand within the available time.
• Avoid unnecessary NPCs, modes, buttons, puzzles, introductory text and decorative features that compete with the core investigation.
• LLM responses should be very short and focused. Long answers make it difficult to collect the necessary evidence within five minutes.
• The three temporal versions should clearly feel like the same person, but their knowledge and behaviour should reflect their respective epochs.
• Pass relevant state to later temporal versions rather than displaying the earlier version’s complete transcript inside the later chat.
• The timer should remain clearly visible throughout every part of the investigation, including conversations.
• Keep the NPC, room, interactable and chat visually connected. Separate pop-up windows and overlapping panels made some Alpha applications difficult to follow.
• If audio is included, keep it minimal and controllable. Delayed or overlapping speech can distract from the investigation.
• Test a clean clone of the repository on another machine. Check resource paths, window sizing, CSS, Java/Maven configuration and the course API configuration.
• During the team demonstration, explain important design decisions as the relevant feature appears. Be prepared to locate and explain the associated prompts and Java code.
• Double check that you do not miss any of the must requirements!

Good luck!

Final Version

To be released after Beta presentations