A development server that allows you to break down a Twine project into individual passage files, make changes, and view them in real-time. For now supports only SugarCube format.
twine-dev-server is a project that enables you to decompile a Twine project into separate passage files. It allows you
to make changes and view them in real-time. To get started, you need to run the decompile script on a compiled Twine
project where your static files are located. The script will parse all the files and create two subfolders in the src
directory: static and story. The static folder will contain everything unrelated to the HTML file, while the
story folder will contain the passages, a scripts directory for project scripts, a styles directory for
stylesheets, and a _project.json file that holds the main project information.
Passages by default are stored in Markdown (.md) format. You can use other formats, if you want.
Configure it in the `src/lib/scripts/configs.ts' file.
- Decompile Twine projects into separate passage files.
- Real-time development server to view changes instantly.
- Supports rearranging and renaming passages.
- Combine multiple scripts and stylesheets during compilation.
- Compatible with Twine and SugarCube.
-
Clone the Repository
Pull the project from GitHub:
git clone https://github.com/laruss/twine-dev-server.git
-
Install Bun
Make sure you have Bun installed. You can install it with the following command:
macOS/Linux
curl -fsSL https://bun.sh/install | bashWindows
powershell -c "irm bun.sh/install.ps1 | iex"Follow the instructions to add Bun to your path.
-
Install Dependencies
Go to the project directory and install the dependencies:
cd twine-dev-server bun install
To decompile a Twine project, run the following command on your compiled project folder (folder where html file is located):
bun run decompile `/path/to/your/project_folder`This will create static and story subdirectories in your src directory.
WARNING: If you have just an html file, you should put it in empty folder as script will copy all files and folders
from the project folder to the static directory.
To start the development server and watch for changes:
bun run devThe server runs on Elysia.js and is accessible at http://localhost:3000. The project will
automatically recompile when files are saved, created, or deleted in the src directory.
To build the project for distribution:
bun run buildThe compiled project will be located in the dist directory, ready for distribution or import into Twine.
After decompilation, your project will have the following structure:
src/
static/
... (static files unrelated to HTML)
story/
passages/
my_super_name.md
another_passage.md
...
scripts/
---| index.js
---| script.js
...
styles/
---| style1.css
---| style2.css
...
_project.json
- Each passage file is named exactly as it appears in Twine (e.g.,
my_super_name=>my_super_name.md). - The top of each generated passage file contains metadata, which can be removed. However, removing metadata may cause the passage's position in Twine to change upon compilation and losing tags information.
- You can reorganize passages by moving them into subdirectories within
src/story. - To rename a passage, simply rename the file (I am suggesting to use refactoring tools of your IDE to avoid breaking references in other passages or scripts).
File src/story/hello.md:
====================
pid: 7
====================
I am a new node named hello
<<script>>
console.log('from hello', State.variables);
<</script>>File src/story/some_folder/some_passage.md:
Hello from `some_passage` in `some_folder`;
This passage has no metadata, but it will still work;
But it can't be a `start` passage without `pid`;File src/story/some_folder/some_other_passage.md:
====================
name: test
pid: 1
tags:
position: 725,375
size: 100,100
====================
This passage has been made in Twine, now it's in markdown;
You can remove all data from the top of the file if you want, it will still work;
Leave pid though if this passage is the `start` passage;- Scripts can be split across multiple files, but have one main entry point, that should have other scripts imported.
- During compilation, all scripts will be combined into a single file.
- Scripts are located in
src/story/scripts/.
Script files support ES6 syntax and import/export statements.
Also index.js can be renamed to index.ts to enable TypeScript support.
To install external libraries, you can use bun add <package-name> command.
For more information, see the Bun documentation.
Example:
scripts/
---| index.js
---| script.js
index.js:
import { myFunction } from './script.js';
myFunction();script.js:
export function myFunction() {
console.log('Hello from myFunction');
}- Styles can be split across multiple files.
- During compilation, all styles will be combined into single files.
- Styles are located in
src/story/styles/.
The following scripts are available in the package.json:
- dev: Starts the development server and watches for changes.
bun run dev
- decompile: Decompiles a compiled Twine project.
bun run decompile
- compile: Compiles the project without building.
bun run compile
- build: Builds the project for distribution.
bun run build
- lint: Runs ESLint on the
srcdirectory.bun run lint
- pretty: Formats the code using Prettier.
bun run pretty
You can run these scripts using npm as well, if you have it installed.
This project is licensed under the MIT License - see the LICENSE.md file for details.
https://github.com/laruss/twine-dev-server
- Twine - An open-source tool for telling interactive, nonlinear stories.
- SugarCube - A free (gratis and libre) story format for Twine/Twee.
- Write tests
- Add possibility to create empty project
- Add easy support for third-party libraries (e.g., React)
- Add TypeScript support in scripts
- Add support for SCSS and other CSS preprocessors
- Add support for other Twine formats