Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
This branch is 108 commits behind OASIS-learn-study:develop.

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

minecraft-storeys-maker Build Status

Minecraft extension to make your own stories in, with and for Minecraft - it's like being a movie director!

Minecraft Stories Maker

Please do Star & Watch this GitHub project if you like it!

Scratch integration

This project has four parts, delivered separately:

  1. Minecraft plugin, described below, lets you create stories by writing .story text files.
  2. Another Minecraft plugin, described in a separate README, lets you script Minecraft with Scratch!
  3. Third option, in another separate README, create a javascript 'story'.
  4. Separately, and not (yet?) Minecraft integrated, the Engine.

Get it

Place the storeys-master-all.jar into your Minecraft, typically the mods/ directory of a Vanilla server.

Tested on Sponge Vanilla 7.0.0 (Minecraft 1.12.1) and Sponge Vanilla 5.1.0 (Minecraft 1.10.2). Likely works on Sponge Forge as well.

Use it

Write your own .story file, e.g. see hello.story.

Run it with /story <story-name> (without .story suffix, so e.g. /story hello)

Story syntax

// Comment

= Title
== Subtitle

/tp 0 0 0

%await 2s

/tp -235 64 230 17 12

This is something which will appear on the chat.

@entityName this is something that the entity will "narrate" (in its name tag, like a speech bubble in a cartoon)
you can use more than one line; everything until the next paragraph break (double new line) will be part of the narration.
You do not have to break up the text yourself - it will automatically be "chopped up" appropriately by itself.

Now this will appear on the chat again (unless there is a '@' character in front again).

You can of course use ANY Minecraft command in any line that starts with the '/' character, not just /tp.

An entity's name must be given to your actors with a name tag (created via an Anvil), as always in normal Minecraft.

The %await action is is useful e.g. if you are teleporting your viewer around to show him a scenery, and need the story to "pause" (to appreciate the beauty of your creation). You do not need to explicitly use this otherwise, as the story automatically pauses appropriately when narrating, showing titles and chat.

You can obviously mix the order and repeat titles, comments, chats, narrations, commands and actions.


  • /story <story-name> plays a story, read from config/storeys/stories/<story-name>.story
  • /narrate <entityName> Text.. makes an entity "narrate" the Text

Build it


./gradlew build

Locally in a container (Dockerfile)

docker build -t minecraft-storeys-maker .

docker run -it --rm -e OPS=73551f35-7acb-45c0-bc65-8083c53eec69 \
    -v $HOME/MinecraftData:/data:Z \
    -p 25565:25565 -p 8080:8080 -p 7070:7070 minecraft-storeys-maker

Now you can use the /make (AKA /scratch) command to get the URL to Scratch where you can "make a plugin". (The OPS with your Minecraft ID is required because the command requires permission; alternatively use permissions.)

If you want to run on a diffenent host then localhost, you'll need to set the following environment variables:

storeys_gui = http://<EXTERNAL-IP>:7070/index.html
storeys_eventBusURL = http://<EXTERNAL-IP>:8080/


A Series N1: f1-micro (1 vCPU, 614 MB memory) is too small and crash loops; but a Series N1: g1-small (1 vCPU, 1.7 GB memory) seems to suffice for 1 or 2 player; otherwise a N1 standard or a e2-medium (2 vCPU, 4 GB memory) or more is recommended.

Remember to set the environment variables as above, add a persistent /data volume, and create an appropriate firewall rule.

TODO Cost: $x VM + $y PD + $7 (?) static IP + $z Ingress+Egress = $TBD.


Seriously, "storeys" (not "stories") Maker, are you mental? Yeah.. just to avoid any possible confusion with Minecraft Story Mode! ;-)

License? Contributions? Licensed under the GNU Affero General Public License v3.0 (AGPLv3). Contributions most welcome.


Minecraft extension to make your own stories in, with and for Minecraft - it's like being a movie director!



AGPL-3.0, Unknown licenses found

Licenses found






No packages published


  • Java 90.3%
  • TypeScript 5.4%
  • JavaScript 2.5%
  • Shell 1.0%
  • Gherkin 0.4%
  • HTML 0.3%
  • Dockerfile 0.1%