Write your own case

You can write your own murder mystery for Damning Details and share it with other players. You don't need to know how to program. A case is one text file that holds your story, its people, places and clues. Aftermath stories, pictures and music are optional extras.

This guide shows you how to plan a case, walks through a complete example you can copy, and explains every part of the file. If an AI assistant helps you, give it this guide too.

How a case works

• A case is a folder. It holds a file called mission.en.json and, if you like, pictures and music.
• To share it, zip the folder. The zip is the case file. Players import it under Start New Case → Extras → Import, in the desktop and Android apps.
• The file is written in JSON. JSON is a plain-text way of writing labels and values. You can edit it in a free editor that highlights mistakes, such as VS Code, or in Notepad on Windows. Avoid word processors, which can turn straight quotes into curly ones and break the file.

When a player imports your case, the game checks it. If anything is wrong, the case is refused with a single message that doesn't say why, so use the checklist below before you share.

Plan your story first

Write down what really happened before you write a single clue. A good mystery is a true story that the player uncovers piece by piece.

1. The crime. Who died, where, how and when?
2. The killer. To win, the player must prove three things about the killer:
   • Means: how they did it, such as the weapon.
   • Motive: why they did it.
   • Opportunity: when they had the chance, usually by breaking their alibi.
3. The suspects. Every suspect needs a secret that makes them look guilty. The innocent ones' secrets become your red herrings.
4. The witnesses. Each witness saw or heard something useful.
5. The places. Two to four places are plenty for a first case. Put each person somewhere they would naturally be.
6. The timeline. List the events in order, with times. Check that everyone could be where you say, when you say.
7. The discoveries. For every fact the player needs, decide how they learn it: a clue they find, something a person says, or a conclusion they work out by combining clues.

Keep your first case small: two or three suspects, one or two witnesses, and eight to twelve clues.

Make it fair

• The player must be able to prove the solution from clues they can find. The killer's confession can add feelings and detail, but not the missing proof.
• Give each innocent suspect a real reason to look guilty, and a way for the player to see past it.
• People shouldn't hide something obvious for no reason. A new clue can give them a reason to say more, such as being shown proof.
• Give the player at least one detail that only the killer could explain.

How clues fit together

The player collects clues in three ways:

• Physical: found by examining something, such as a drawer, a bag or the victim's body. A person can also hand one over.
• Testimony: what people say when the player questions them, or when the player shows them clues.
• Deduction: a conclusion the player works out by putting two or more clues together, such as two accounts that contradict each other.

Clues can depend on each other:

• Locks and keys: a container stays locked, or hidden, until the player finds the clue that opens it.
• Showing clues to people: after the player finds certain clues, they can show them to a person, who then says something new. The player must pick exactly the right clues, so make each one clearly matter to the question.
• Deductions: the player must pick exactly the clues that support the conclusion.

Every clue has a role in the solution:

• Critical: proof against the killer. You need at least one each for means, motive and opportunity, and the player must use every critical clue in the accusation.
• Misleading: a red herring, such as an innocent suspect's secret. The player must leave these out of the accusation.
• Prerequisite: a stepping stone, such as a key or an account the player needs for a later clue. It never goes in the accusation.

The example case

Curtain Call at the Quillfield Playhouse is a short case you can copy and change. This section spoils it.

Victor Hale, a theatre director, is found dead on the stage after a dress rehearsal. Three people are in the building:

• Iris Calloway, his star, is the killer. Victor gave her role to her understudy and told her after rehearsal.
• Simon Pratt, his stage manager, is the red herring. He took money from the box office, and Victor found out.
• Ada Finch, the usher, is the witness who found the body.

Here is how its clues connect:

MEANS        prop trunk → Bloodstained Stage Weight

MOTIVE       Victor's body → Desk Key
             Desk Key opens the desk drawer → Understudy's Contract

OPPORTUNITY  Question Ada → Ada's Account
             Show Ada the Bloodstained Stage Weight and Ada's Account → Ada's Sighting
             Question Iris → Iris's Account
             Deduce from Iris's Account and Ada's Sighting → Iris's Alibi Contradiction

RED HERRING  cash box → Box Office Takings Book
             Show Simon the Box Office Takings Book → Simon's Explanation

The quickest solve takes ten turns. The example also has optional aftermath stories, some of which depend on what the player found. It has no pictures or music, which are optional too.

To play it, download quillfield-playhouse.zip and import it. To read its file, open mission.en.json.

To start your own case from it, unzip it, rename the folder, change the ID to the new folder name, and edit mission.en.json. On Windows, Extract All puts the case inside a second folder of the same name: use the inner one, the folder that holds mission.en.json.

Reading and writing JSON

• Text goes in double quotes: "NAME": "Victor Hale".
• Put a comma between items, but not after the last one in a list or group.
• { } holds named parts, and [ ] holds a list.
• true and false answer yes-or-no questions, and null means "none".
• Inside text, write \" for a double quote and \n\n to start a new paragraph.
• Wrap words in **double stars** to show them in bold. The example uses bold for people and for things worth examining.
• In the text of places, objects, conversations, the body, clues, the confession and aftermath stories, {player} becomes the detective's name. It doesn't work in the opening brief or in short fields such as BIO and DESCRIPTION. Don't use curly brackets for anything else.
• Names must match exactly wherever they appear, including capital letters. "Dressing Room" and "dressing room" are different places.

What each part means

The file has two parts, as in the example: the opening brief, NARRATIVE, at the top, and GAME_BIBLE, which holds everything else. Every part is required unless it's marked optional. You can leave an optional part out, or set it to null.

The case card and opening

Places and objects

CRIME_SCENE → LOCATIONS lists the places. Each place has two texts in NARRATIVE: first, for the first visit, and again, for later visits. Mention the people waiting there and the things worth examining.

LOCATION_OBJECTS lists ordinary things to examine in each place, with first and again texts. They hold no clues, but they add atmosphere and can unlock an aftermath story. They're required: every place needs one to three of them. Things that hold clues, such as the prop trunk, aren't listed here: naming one as a clue's CONTAINER is enough.

Name places and things so they read well after "the": "Go to the Stage", "Examine the prop trunk". Avoid names like "Room 4" or "Simon's Room".

People

SUSPECTS and WITNESSES list the people the player can question.

The answer to "Where were you at the time?" isn't a clue, so the player can't show it to anyone or use it in a deduction. Put a claim the player must break in a testimony clue instead, like Iris's Account in the example.

The VICTIM has NAME, ROLE, LOCATION and BIO, plus:

• METHOD_OF_DEATH: how they died. Players see it once they've found every means clue, so don't name the killer here.
• NARRATIVE → first and again: what the player sees when examining the body.

Write the victim's BIO in the present tense, as if they were alive, because the briefing puzzle shows it among the others.

Clues

EVIDENCE_AVAILABLE lists every clue. Each clue starts with a short key of your choice, such as "desk_key", which other parts of the file use to refer to it.

Some fields depend on the clue's type:

• Testimony, and items a person hands over: CONTAINER is the person's name, and LOCATION is where they wait. Without REQUIRES, the player gets it by asking them "What can you tell me?". With REQUIRES, the player gets it by showing that person exactly those clues.
• Deduction: LOCATION and CONTAINER are null, REQUIRES lists at least two clues, and NARRATIVE explains the reasoning.
• Prerequisite: CATEGORY and POINTS_TO can be null when the clue is about nobody in particular, like the key.

The solution

KILLER_LOGIC holds your notes on the killer's MOTIVE, MEANS and OPPORTUNITY, which players don't see, and the NARRATIVE the player reads after a correct accusation: the detective's explanation and the killer's confession. All four are required.

CHRONOLOGY is your timeline of what really happened. Players don't see it, but it's required: it keeps your story straight, and it helps anyone, including an AI assistant, who works on your case.

The aftermath (optional)

After the case is solved, the player can read what became of everyone. Without AFTERMATH, the case ends after the confession. AFTERMATH holds groups of stories, each under a short name of your choice, such as "simon". From each group, the player reads the first story whose REQUIRES they've met. The example has three kinds of group:

• Always told: Iris's group has one story without REQUIRES, so every player reads it.
• Changed by a discovery: Simon's group starts with a story that requires Simon's Explanation, followed by a fallback without REQUIRES for everyone else. Put the fallback last.
• Added by a discovery: the poster group has one story, which requires examining the framed poster. Players who skip the poster read nothing from this group.

REQUIRES can list clue keys, an ordinary object the player examined, written as ["Director's Office", "framed poster"], or a conversation the player had, written as ["Simon Pratt", "question"] or ["Simon Pratt", "ask_alibi"].

Each story needs a TITLE, unique within the case, and its NARRATIVE. REQUIRES is optional, and so is PORTRAITS, which lists the people whose pictures, or initials, appear above the title. A fallback must not mention a secret the player may have missed.

Pictures and music (optional)

A case plays fine without any. To add them, put the files in the case folder and name them in the file:

• "IMAGE" on a place, person, ordinary object, physical clue, deduction or aftermath story, such as "IMAGE": "location-stage.jpg". The official cases use 800×450 JPEG files for scenes and 160×160 PNG files for portraits.
• "CONTAINER_IMAGE" on a locked clue: the picture of its locked container.
• MUSIC: an INVESTIGATION list of songs for the investigation, an AFTERMATH list for the aftermath, or both. Each song has an INTRO and a LOOP file, and optionally an OUTRO. A song with an outro plays its intro, its loop four times and its outro, then moves on to the next song. A song without one repeats its loop. Without MUSIC, the game's own music plays.

"MUSIC": {
  "INVESTIGATION": [
    {"INTRO": "music-backstage-intro.mp3", "LOOP": "music-backstage-loop.mp3", "OUTRO": "music-backstage-outro.mp3"}
  ],
  "AFTERMATH": [
    {"INTRO": "music-encore-intro.mp3", "LOOP": "music-encore-loop.mp3"}
  ]
}

Use only the file name, spelled exactly as in the folder. Share only pictures and music you have the right to share.

Writing tips

• Write times on the 24-hour clock, such as 22:10.
• Players visit places and talk to people in any order. Don't write "as you saw earlier" unless that clue is in REQUIRES.
• again texts must still be true after the player has found everything.
• A clue the player gets by asking "What can you tell me?" or by examining the body is read straight after the person's answer or the body's text, so write it to carry on from there, as Iris's Account and the Desk Key do.
• Keep DESCRIPTION short and factual, and attribute claims: "Iris says she last saw Victor at 22:00", not "Iris last saw Victor at 22:00".
• When a person speaks after being shown clues, let the detective's question mention each clue, so the player can see why it matters.
• If you write aftermath stories, keep each to a few short paragraphs, in the past tense.

Checklist before you share

The game checks all of this when your case is imported.

The folder and file

• The folder name and ID match exactly. Lowercase letters, numbers and hyphens are safest.
• The ID isn't tutorial, tregarrow-house, halley-research-station, palmyra-hotel or generated. Adding your name, such as quillfield-playhouse-sam, keeps it unique, so that a future official case can't take its name.
• The file is named mission.en.json, sits directly inside the case folder, and is saved as plain text in UTF-8, the usual setting.
• If you added pictures or music, every file the case names is in the folder.

People and places

• Exactly one suspect has "IS_KILLER": true.
• Every person has a different name, and so does every clue.
• START_PLAYER_LOCATION and every LOCATION of a person or a physical or testimony clue is one of the places, spelled exactly the same.
• Every place has a person in it or a clue to find.
• Every place has one to three ordinary objects. None shares its name with a person, or with a clue's CONTAINER in the same place.
• No CONTAINER has the same name as a place.
• Every witness gives at least one clue.

Clues

• There is at least one critical clue each for "means", "secret" and "alibi", and every critical clue points to the killer.
• Every critical or misleading clue has a CATEGORY and points to a suspect.
• Testimony and items a person hands over are in that person's place.
• Every clue key in REQUIRES belongs to another clue. No clue requires itself, and no two clues require each other, even by a longer loop.
• No chain of clues is longer than four: in the example, Bloodstained Stage Weight → Ada's Sighting → Iris's Alibi Contradiction is three.
• A person gives at most two testimonies when questioned, and at most two for each set of clues shown to them. Items they hand over don't count.
• Every deduction has null for LOCATION and CONTAINER and requires at least two different clues. A prerequisite deduction is required by another clue.
• NARRATIVE_LOCKED appears only on a physical clue that has REQUIRES and isn't on a person or the body. Other clues in the same container need at least the same REQUIRES.
• Clues in the same container spell its name exactly the same.

Text

• Every text is filled in: first and again for every place, ordinary object and the body, question for everyone, ask_alibi for every suspect, every clue's NARRATIVE and the confession.
• No curly brackets appear except {player}.

Aftermath and music, if you add them

• Every aftermath group has at least one story, and every story has its text and a title that no other story uses.
• PORTRAITS and REQUIRES name real people, clues, objects in their places and conversations. Only suspects have ask_alibi.
• No story requires everything that an earlier story in its group requires, or it could never be shown.
• Each song has an INTRO and a LOOP, and optionally an OUTRO, and nothing else.

Import, test and share

1. Zip the folder. On Windows, right-click it and choose Compress to ZIP file, or Send to → Compressed (zipped) folder; on a Mac, right-click it and choose Compress. The zip must hold the folder itself, not just the files inside it, and only one case.
2. In the game, choose Start New Case → Extras → Import and pick the zip.
3. Play it through twice: once as quickly as you can, and once finding everything. Check that the text makes sense in different orders and, if you wrote an aftermath, that each story appears when it should.
4. To change your case, edit the folder, zip it again, then Remove the case in Extras and import the new zip. Removing a case also deletes its saved progress if it's the case in progress.
5. Share the zip with other players.

Working with an AI assistant

An AI assistant can turn your story notes into a case file, or check one you wrote. To get good results:

• Give it this guide and your story, including your timeline.
• Ask it to follow the example's layout and to keep your story's facts.
• Ask it to go through the checklist item by item, and to check that the JSON is valid.
• Ask it to walk through the quickest solution and a full playthrough, checking that every clue can be found and that every text reads well in any order.
• Read the result yourself, and play it before you share it.