This Unity package allows you to integrate inkle's ink narrative scripting language with Unity and provides tools to compile, play and debug your stories.
-
Using ink in your game: Allows running and controlling ink files in Unity via the C# runtime API.
-
ink player: Provides a powerful Ink Player Window for playing and debugging stories.
-
Automatic compilation:
.inkfiles are imported by Unity as anInkFileasset and compiled automatically. -
Inspector tools: Provides an icon for ink files, and a custom inspector that provides information about a file.
The recommended way to install ink is as a UPM package via Unity's Package Manager. A few other options are listed below.
- Open the Package Manager (Window > Package Manager), click the + button and choose Install package from git URL…
- Enter
https://github.com/inkle/ink-unity-integration.git#upm - It installs at Packages > Ink Unity Integration. Demos can be imported from Packages > Ink Unity Integration > Demos.
If you'd like the Package Manager to notify you when a new version is available, install through OpenUPM instead. It distributes the same package through a scoped registry — follow the instructions there.
Best if you want to edit the source, or don't have git installed. This imports the source into your Assets folder.
- Download the latest .UnityPackage.
- Open the downloaded file to import it into your Unity project.
Clone or fork the GitHub repo if you want to work from or contribute to the source. To just install the latest version, use the git URL as described in Via the Package Manager above; to embed an editable copy, move the Packages/com.inkle.ink-unity-integration folder into your own project's Packages folder.
For convenience a .UnityPackage is hosted at the Unity Asset Store. This version is updated rarely, and so is not recommended.
This project includes a demo scene, providing a simple example of how to control an ink story with C# code using Unity UI.
(If you imported this package as a UPM, then you must first import the demos from Packages > Ink Unity Integration > Demos)
To run a demo, double-click the scene file at the root of the demo folder to open it, and press the Play button at the top of the screen to start it.
The C# API provides all you need to control ink stories in code; advancing your story, making choices, diverting to knots, saving and loading, and much more.
It is documented in the main ink repo.
For convenience, the package also creates an (Help > Ink > API Documentation) menu option.
For more information on writing with ink, see the documentation in the main ink repo.
For convenience, the package also creates an (Help > Ink > Writing Tutorial) menu option.
For assistance with writing or code, Inkle's Discord forum is full of lovely people who can help you out!
To keep up to date with the latest news about ink sign up for the mailing list.
.ink files are compiled to a runnable story automatically by a Unity ScriptedImporter, whenever you create or edit one (or any file it INCLUDEs). There's no separate compile step and no .json file to manage — the compiled story is stored in the imported InkFile asset. Read it with inkFile.storyJson and pass it to new Ink.Runtime.Story(...).
Master files (any .ink not INCLUDEd by another file) compile to a story; include files compile as part of their master. To also compile an include on its own, tick Compile As Master File in its import settings.
Compiling at runtime: the ink compiler ships in builds (part of the Ink-Libraries assembly), so you can compile .ink in-game if you need to. If you don't, see WebGL best practices to trim it.
The Ink Player Window (Window > Ink Player) allows you to play stories in an editor window, and provides functionality to edit variables on the fly, test functions, profile performance, save and load states, and divert.
To play a story, click Play in Ink Player on an ink file's inspector, or assign an InkFile in the Ink Player window.
Editor Attaching: Attaching the InkStory instance used by your game to the Ink Player window allows you to view and edit your story as it runs in game.
See BasicInkExampleEditor.cs in the Basic Demo for an example of how to:
- Show an attach/detach button on an inspector
- Automatically attach on entering play mode
More information on using and extending Ink Player Window
Selecting an ink file shows any compile errors, warnings and TODOs, and maps out its include hierarchy: whether it's a master or an include file, and the files it includes and is included by.
WebGL builds should be as small as possible. The ink compiler is bundled with the runtime in the Ink-Libraries assembly, so it ships in builds even though most games only use it at edit time. If build size matters and you never compile ink at runtime, you can split the compiler (InkLibs/InkCompiler) into its own editor-only assembly definition so it's stripped from builds — you'll also need the editor assembly to reference that new assembly. The runtime (InkLibs/InkRuntime) itself never needs the compiler.
-
Is the Linux Unity Editor supported?
Yes!
-
What versions of Unity are supported?
Ink for Unity 2.0 supports Unity 2022.3 LTS and above. (The 1.x line supports 2020 LTS and above.)
Ink is free, forever; but we'd really appreciate your support! If you're able to give back, generous donations at our Patreon mean the world to us.
Looking for help or want to meet likeminded writers/developers? Come say hello on our Discord server!
ink and this package 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. View the full licence Here