Screenplay files
An event model on a Studio board is a Screenplay model: modules, features, slices, commands, events, read models, screens and specifications, written in .play files. Studio is one place to edit that model. The .play files are another, and they can be the source of truth that lives next to your code.
This page covers the developer’s side: getting the files out, getting them back in, and keeping them in Git. The language itself is described at cratis.io.
What an export holds
Section titled “What an export holds”Open Project options > Export to download the open event model. You can choose:
| Export | What you get |
|---|---|
| Screenplay file | One .play file holding the whole event model |
| Screenplay folder | A ZIP of .play files, one per module, feature and slice, laid out as folders |
| Mermaid | A Mermaid eventmodeling diagram. There is also Export feature to Mermaid for a single feature |
| Event Modeling JSON | A document in the official Event Modeling Specification format |
Use the Screenplay folder when you want the model in a repository, because small files give small diffs and sensible merges. Use the single file when you want to hand the model to a person or a tool in one piece.
The folder layout
Section titled “The folder layout”The folder export mirrors the board. Module folders hold feature folders, and feature folders hold slice folders. The names below are only an illustration:
model/ Catalog/ module Products/ feature AddProduct/ slice ... Sales/ Orders/ ...Beside the .play documents, the folder carries everything the model names that a .play file cannot hold:
- the sketches, mockups and images of your screens, saved byte for byte,
.screenplay/notes.json, which holds the issue links of your slices.
The export reports what the board holds that the files could not carry. Read those diagnostics before you decide the files are a complete copy.
Import
Section titled “Import”Project options > Import reads a model into a board:
| Import | Use it for |
|---|---|
| Screenplay file | A single .play file |
| Screenplay ZIP | A ZIP of .play files imported as one application. The ZIP can be up to 8 MiB |
| Screenplay folder | A folder of .play files you pick from disk |
| Event Modeling JSON | An official Event Modeling Specification document |
Studio compiles what you pick before it changes anything, and shows the result as Preview import. Compile errors are listed with their line and column. Anything the import cannot carry shows under Some of the document will not be added. Select Accept & Import to import, or Cancel to leave the board as it is.
An import brings the screens’ sketches, mockups, images and issue links along with the model.
Round-tripping
Section titled “Round-tripping”A model can go out and come back. These are the limits worth knowing:
- Concepts that already exist on the board are left unchanged by an import, so their generation strategy and rules do not change. Studio warns when this happens.
- Generation strategies that Screenplay cannot express (
pattern,randomandrule) are dropped with a warning on import. - A concept that is marked as personal data and also generated keeps its personal-data classification and loses generation, with a warning.
- Rules on a generated concept are checked against the strategy on export. A rule that can never hold is refused on export and its concept is left out, while the rest of the model still exports.
Read the import preview’s warnings every time. They name what an import will not carry.
Keep the files in Git
Section titled “Keep the files in Git”Instead of exporting by hand, connect a board to a repository. Studio then commits the model there as you work.
You need a project with a repository connected. See Build and deliver for connecting one.
- Open Project options > Keep in sync with Git.
- Choose the Branch and the Folder inside the repository, for example
model. The folder’s contents are replaced by the board’s files. - Optionally turn on Offer changes pushed to these files for import into the board.
- Select Keep in sync.
What Studio commits is exactly what the Screenplay folder export holds. Each commit message names the board and lists the files added, changed and removed. Studio waits until the board has been quiet for a while, so a modeling session becomes a few commits, not one per keystroke. A board that keeps changing is still committed after a longer delay.
Studio reaches the repository through the application’s GitHub App installation. No Git credentials are stored for the sync.
When the repository changes
Section titled “When the repository changes”Studio never overwrites a change it has not seen. When someone changes the board’s files in the repository, the status says Someone changed the board’s files in the repository and Studio stops committing. The dialog lists the files that differ, and you choose:
- Import the repository’s version, which goes through the usual import preview and brings the sketches, mockups, images and issue links in the folder back with it.
- Commit Studio’s version on top, which keeps the repository’s change in history and then replaces the folder’s files with the board’s.
With Offer changes pushed to these files for import into the board on, a change in the repository with no change on the board is offered for import. When both sides changed, Studio reports the conflict and overwrites neither.
A sync that fails shows why. Select Stop syncing to end it. Nothing already committed is removed.
Working with the files in your editor
Section titled “Working with the files in your editor”Because the files are plain text, an editor, a pull request review or a script can work on them. The safest flow:
- Let Studio commit the board to the branch.
- Change the
.playfiles on that branch, or on a branch of your own. - Merge into the synced branch, and use Import the repository’s version in Studio to bring the change onto the board.
Edit the model in one place at a time. If the board and the files both change between two syncs, you will be asked to choose.
Read a model without signing in
Section titled “Read a model without signing in”The viewer at https://view.cratis.studio/?url=<URL-encoded address> fetches a public .play document, compiles it, and draws it on the same board Studio uses, read-only, with pan and zoom. It needs no sign-in. It is a convenient way to put a model in a README or a blog post.
Related
Section titled “Related”- Agent context hands part of a model to a coding agent.
- Connect an AI agent over MCP edits a model through Screenplay sessions.
- Event modeling explains the model behind the files.
- The Screenplay language at cratis.io.