devenlu/ink-1

inkle's open source scripting language for writing interactive narrative.

ink

Ink is inkle's scripting language for writing interactive narrative, both for text-centric games as well as more graphical games that contain highly branching stories. It's designed to be easy to learn, but with powerful enough features to allow an advanced level of structuring.

Here's a taster from the tutorial.

- I looked at Monsieur Fogg 
*   ... and I could contain myself no longer.
    'What is the purpose of our journey, Monsieur?'
    'A wager,' he replied.
    * *     'A wager!'[] I returned.
            He nodded. 
            * * *   'But surely that is foolishness!'
            * * *  'A most serious matter then!'
            - - -   He nodded again.
            * * *   'But can we win?'
                    'That is what we will endeavour to find out,' he answered.
            * * *   'A modest wager, I trust?'
                    'Twenty thousand pounds,' he replied, quite flatly.
            * * *   I asked nothing further of him then[.], and after a final, polite cough, he offered nothing more to me. <>
    * *     'Ah[.'],' I replied, uncertain what I thought.
    - -     After that, <>
*   ... but I said nothing[] and <> 
- we passed the day in silence.
- -> END

Getting started

Download Inky, our ink editor, and the follow either:

• The basics tutorial if you're non-technical and/or if you'd like to use ink to make a web-based interactive fiction game
• The full tutorial if you want to see everything that ink has to offer.

For those who are very technically-minded, you can also use inklecate directly, our ink command line compiler (and player).

To keep up to date with the latest news about ink sign up for the mailing list.

Writing with Unity

• Download the latest ink-unity-integration package, or grab it from the Unity AssetStore, and place in your project.
• Create a .ink text file such as myStory.ink, containing the text Hello, world!.
• Select the file in Unity, and you should see a Play button in the file's inspector.
• Click it, and you should get an Editor window that lets you play (preview) your story.
• Follow the tutorial: Writing with Ink.

Advanced: Using inklecate on the command line

• Download the latest version of inklecate (or build it yourself, see below.)

• Create a text file called myStory.ink, containing the text Hello, world!.

• On the command line, run the following:

  Mac: ./inklecate -p myStory.ink

  Windows: inklecate.exe -p myStory.ink

  Linux: mono inklecate.exe -p myStory.ink

  • To run on Linux, you need the Mono runtime and the Mono System.Core library (for CLI 4.0). If you have access to the debian repository, you can install these using:
    sudo apt-get install mono-runtime libmono-system-core4.0-cil

  The -p option uses play mode so that you can see the result immediately. If you want to get a compiled .json file, just remove the -p option from the examples above.

• Follow the tutorial: Writing with Ink.

Integrating into your game

Full article: see Running Your Ink.

For a sample Unity project, see The Intercept.

Ink comes with a C#-based (or JavaScript-based runtime engine that can load and run a compiled ink story in JSON format.

To compile the ink, either export from Inky (File -> Export to JSON). Or if you're using Unity, you can use the ink-Unity-integration package which will automatically compile your ink for you whenever you edit it either in Inky or in an editor of your choice.

Advanced: You can also use the inklecate command line tool to compile ink stories, or you can call the compiler from C# code yourself.

ink isn't designed as an end-to-end narrative game engine. Rather, it's designed to be flexible, so that it can slot into your own game and UI with ease. Here's a taster of the code you need to get started:

using Ink.Runtime;

// 1) Load story
_story = new Story(sourceJsonString);

// 2) Game content, line by line
while(_story.canContinue)
    Debug.Log(story.Continue());

// 3) Display story.currentChoices list, allow player to choose one
Debug.Log(_story.currentChoices[0].choiceText);
_story.ChooseChoiceIndex(0);

// 4) Back to 2
...

The development of ink

Build Requirements

Windows:

• Visual Studio (e.g. Community edition), Xamarin, or Unity's own version of MonoDevelop.

Mac:

• Xamarin, or Unity's own version of MonoDevelop

Linux:

• Mono. For detailed installation instructions, see Installing Mono on Linux.

Build

1. Load up the solution file - ink.sln.
2. Select the Release configuration and choose Build -> Build All (or Build Solution in Visual Studio).
3. The compiler binary should be built in inklecate/bin/Release (or x86), while the runtime engine DLL will be built in ink-engine-dll/bin/Release/ink-engine.dll

Note that the executable requires Mono on Mac or .NET on Windows. On Windows this isn't a problem since it ships with .NET, but on Mac you need Xamarin for Mono. The build_release.command file in the repo is a Mac script that will bundle up both Mac and Windows versions, and the Mac version will be bundled with the Mono runtime so that the end user doesn't need Xamarin/Mono installed.

How to contribute

We’d of course appreciate any bug fixes you might find!

We're using GitHub issues both as a discussion forum and as a bug tracker, so create a GitHub issue if you want to start a discussion or request a feature, and please label appropriately. Or if you want to get in touch with us directly, email us.

We also have a Discord server, where you may find other people using ink to chat with (as well as inklers!)

Architectural overview

See the architectural overview documentation for information about the pipeline of the ink engine, and a birds-eye view of the project's code structure.

License

ink is released under the MIT license. Although we don't require attribution, we'd love to know if you decide to use ink a project! Let us know on Twitter or by email.

Support us!

ink is free forever, but represents multiple years of thought, design, development and testing. Please consider supporting us via Patreon. Thank you, and have fun!