Cluenite

A Twitch detective game where chat inspects clues, connects evidence, and earns the ending together, across one stream or two.

Comment

Inspiration

A Twitch chat can spot a tiny detail, argue about what it means, and turn an ordinary stream into a shared story. We wanted to build a game around that moment: a community looking at the same mystery and gradually earning an explanation together.

The starting question was simple: what if chat could investigate, rather than only choose the most popular answer?

Cluenite gives viewers clues to inspect, records to connect, and theories to test. The streamer guides the pace, while the community supplies the observations. The ending follows the evidence they establish.

What it does

Cluenite is a detective game built for Twitch streamers and their communities. Viewers participate through ordinary Twitch chat; they do not need to install another application. The host runs the investigation in a browser and can place a read-only presentation in OBS.

There are three live cases:

  • Quick Case — The Gallery Shadow. A gallery alarm sounds even though the main door stayed locked. Chat investigates the available clues and works toward a supported verdict.
  • Mystery Live — The Missing Festival Trophy. A trophy disappears around a blackout. Viewers collect evidence, reconstruct the sequence of events, and challenge theories before reaching an explanation.
  • Co-op — Signal of the Invisible Ship. Two consenting broadcasters investigate from different stations. Each community has access to different information, so a breakthrough depends on sharing the relevant evidence.

The basic loop is easy to follow: inspect a clue, connect what it establishes, test an explanation, and submit a verdict when the proof is ready. Commands such as !look <clue-id>, !link <evidence-id> <evidence-id>, and !solve <verdict-id> turn chat messages into investigation actions. The interface shows the commands and identifiers relevant to the current case.

A correct guess alone does not finish the investigation. The server checks the required proof, and repeated messages cannot manufacture additional progress. An individual viewer can make a useful contribution without winning a popularity contest.

Streamers can start, pause, resume, stop, and revisit saved sessions. OBS links are scoped, expire, and can be replaced or revoked. The broadcast presentation shows the investigation without exposing the host's controls.

For people who want to learn before connecting Twitch, we also built three browser practice cases: A Missing Manuscript, Pearls on the Night Express, and The Lighthouse Went Dark. These teach searching, deduction, and evidence sharing through local gameplay. Their chat and partner behavior are explicitly scripted; they are separate from live Twitch sessions.

How we built it

The interface uses Vue 3, TypeScript, and Vite. PixiJS draws the gameplay environments, interactive objects, light, weather, and discovery feedback. GSAP supports the animation system. We developed a consistent visual language of walnut, brass, parchment, and restrained warm light so the investigation remains readable while still feeling like a mystery.

We spent substantial time on the playing surface. Secondary panels open when needed, discoveries appear without blocking the next click, and practice illustrations can switch between full and compact views. Responsive layouts, fullscreen controls, scrolling, pause behavior, and reduced-motion support help the same investigation work across different screens.

The backend runs on Node.js and Fastify, with Socket.IO delivering authorized session updates. PostgreSQL stores sessions and accepted progress. Shared Zod contracts validate the data exchanged between the browser and server, and a separate TypeScript engine applies the case rules.

Twitch integration uses OAuth for broadcaster authorization, the Twitch API for the required platform operations, and EventSub over WebSocket to receive chat messages. Accepted viewer actions pass through the server before they change the investigation. Private co-op information is projected separately for each station.

We also implemented reconnect and authorization recovery, duplicate-action handling, saved-session continuation, explicit case switching, and OBS credential replacement. These details matter during a stream: the investigation needs to remain understandable when a connection drops or a host returns to an unfinished round.

The public application is hosted on Render. The repository includes setup instructions, environment examples, authored cases, runtime assets, and dated verification records.

How we used Codex

OpenAI Codex was a development tool throughout the build. We used it to inspect the repository, refine the architecture, implement backend and frontend changes, diagnose failures, and verify the result.

Its work included the shared TypeScript contracts, deterministic investigation rules, PostgreSQL persistence, Twitch authorization and EventSub recovery, host and co-op flows, OBS setup, and automated tests. It also helped develop the Pixi environments and refine the layout when controls, evidence notices, or panels competed for space.

We worked iteratively: define a concrete behavior, make a bounded change, inspect the rendered result, and check the relevant tests. For example, visual iteration led to clearer theory panels, full and compact practice illustrations, nonblocking discovery notices, and better use of the available screen.

Codex also helped organize the documentation, examine the source before publication, and connect local verification with GitHub CI. We kept the distinction between a feature being implemented, a synthetic test passing, and a real Twitch interaction being observed.

Claude Code contributed earlier frontend work, and some prototype artwork was created with image-generation tools. The main live environments use native Pixi drawing and animation. The game uses authored cases and explicit rules at runtime; it does not rely on a generative model to decide whether a viewer's verdict is correct.

Challenges we ran into

Making participation meaningful. A mystery loses its appeal if repeated guesses can skip the investigation. We separated observations, evidence, and verdict requirements so the community has a reason to examine the case.

Keeping two communities connected without revealing everything. Co-op needs each station to discover something useful. We had to preserve private views, explicit partner consent, and shared progress while handling invitations, reconnects, and a partner leaving.

Designing for a live broadcast. The host needs controls, viewers need readable progress, and OBS needs a clean presentation. We separated those roles and made chat, evidence detail, and other tools available on demand.

Recovering from interruptions. A lost response should not create a second session, duplicate credit, or leave a streamer unsure whether an action succeeded. We added explicit retry and recovery behavior instead of treating every interruption as a fresh start.

Accomplishments that we're proud of

  • Connecting real Twitch chat to persisted investigation progress and an evidence-checked reveal.
  • Building three distinct live modes with a shared interaction and visual system.
  • Making two-station co-op depend on complementary discoveries rather than duplicated screens.
  • Providing three playable practice cases that explain the mechanics without requiring Twitch sign-in.
  • Building a transparent OBS presentation with scoped, revocable access.
  • Publishing source, setup instructions, and verification boundaries that another developer can inspect.

For the final source publication, workspace typecheck, production build, and repository lint error checks passed. All 62 focused engine/web/provider unit tests and 32 local Chrome browser scenarios passed. Linux GitHub CI also passed its application and PostgreSQL integration checks.

The browser scenarios include live case flows, practice completion, mobile controls, native scene interaction, fullscreen, pause, reduced motion, and OBS presentation. Controlled real-provider checks are documented separately. These results describe the recorded environments; they are not a claim of unlimited audience capacity or complete production player acceptance.

What we learned

The most useful chat interaction is one that changes what the community understands. A small observation becomes satisfying when viewers can see how it supports, contradicts, or strengthens an explanation.

We also learned that reliability is part of the game design. Clear connection status, a recoverable session, and a pause button help the streamer maintain the story when the surrounding infrastructure is imperfect.

Using Codex effectively meant giving it concrete requirements and asking for evidence. A successful build was one checkpoint; watching the actual interface and exercising the complete investigation revealed different problems.

What's next for Cluenite

Our next priority is testing with more streamers and viewers: observing where people hesitate, checking how well newcomers understand the commands, and refining the pacing of each case.

We also want to expand the authored case library, improve accessibility and physical-device performance testing, and complete broader production Twitch and OBS acceptance. Larger audience testing will guide further performance work.

Try it

Public application: https://cluenite-app.onrender.com

Source and setup: https://github.com/AndroLay/cluenite

  1. Open the application and choose Practice from the case-selection page. The three practice cases work without Twitch sign-in and identify their scripted interactions.
  2. Open the guide to learn the chat commands. Public case previews introduce the live cases without starting a session.
  3. For a live round, connect a Twitch account, choose a case, and start it through the host controls. Use the displayed clue and evidence identifiers in that channel's chat.
  4. For co-op, create a lobby, invite the named broadcaster, and have that partner accept before starting.
  5. To broadcast the investigation, create a private OBS link in stream setup and add it as a browser source. Keep that link private.

The current repository source and the deployed build are tracked separately in the project status. The newest source includes refinements beyond the recorded deployment. Reproduction instructions and the scope of each check are linked from the repository.

Built With

Share this project:

Updates

Submission history