ink-unity-integration compiles .ink files as Unity assets

A package for writers, not a runtime you import by hand

inkle wrote ink as a narrative scripting language for interactive fiction, and the Unity package is the bridge between a writer's .ink file and a running game. The package description is modest, a Unity integration for the open source ink narrative scripting language, and the README is clear about the three jobs it does. It lets you run and control ink files in Unity through the C# runtime API, it provides an Ink Player Window for playing and debugging stories, and it compiles .ink files automatically. The audience is a Unity team with narrative content where the story changes often and a compile step that a human has to remember would slow the iteration loop. The C# API covers advancing a story, making choices, diverting to knots, saving and loading, and the package also adds a Help > Ink > API Documentation menu option that opens the runtime documentation without leaving the editor. The writing side has the same convenience, with a Help > Ink > Writing Tutorial menu entry pointing at the ink documentation in the main repository.

The ScriptedImporter removes the .json file from your workflow

The compilation model is the part worth understanding. .ink files are imported by Unity as an InkFile asset and compiled automatically, using a ScriptedImporter, whenever you create or edit one, or edit any file it INCLUDEs. There is no separate compile step and no .json file to manage, and the compiled story lives inside the imported InkFile asset. You read it with inkFile.storyJson and pass it to new Ink.Runtime.Story(...). That is the practical difference from the older approaches, where the ink compiler produced a JSON file that you committed and that silently went stale whenever the source changed. Here the import is the compilation. The include structure is handled in a defined way. Master files, meaning any .ink that is not INCLUDEd by another file, compile to a story, while include files compile as part of their master. If you want an include compiled on its own, the import settings have a Compile As Master File tick box. The compiler also ships inside builds, as part of the Ink-Libraries assembly, so you can compile .ink in game if you need to.

Installing through the Package Manager with a git URL

The recommended installation route is Unity's Package Manager, and the git URL is the one thing you type exactly as given. Open the Package Manager with Window > Package Manager, click the + button and choose Install package from git URL, then enter the URL below.

https://github.com/inkle/ink-unity-integration.git#upm

Note the branch reference in the URL, since that is what selects the package branch rather than the default one. The package lands under Packages > Ink Unity Integration, and the demos arrive separately from the Demos folder inside it, which matters because a UPM import does not pull the demo scenes in automatically. If you import the package this way, you have to bring the demos in yourself before running them. To run one, double-click the scene file at the root of the demo folder and press the Play button, and the demo shows a simple example of controlling an ink story with C# code using Unity UI. There are four other routes, each with a stated reason. OpenUPM distributes the same package through a scoped registry and has the advantage that the Package Manager notifies you when a new version is available. A.UnityPackage download is best if you want to edit the source or do not have git installed, since it imports into your Assets folder. Cloning or forking the repository is the path for contributors, and to embed an editable copy you move the Packages/com.inkle.ink-unity-integration folder into your own project's Packages folder. The Unity Asset Store copy exists for convenience and the README says plainly that it is updated rarely and is not recommended.

The Ink Player Window is where the debugging happens

The Ink Player Window, opened from Window > Ink Player, is a full editor window for playing stories, and its feature list is what makes it more than a preview. It edits variables on the fly, tests functions, profiles performance, saves and loads states, and diverts. You start a story by clicking Play in Ink Player on an ink file's inspector, or by assigning an InkFile in the window itself. The part that changes how you work is editor attaching. Attaching the InkStory instance used by your game to the Ink Player window lets you view and edit the story as it runs in game, so a branching bug becomes something you can poke at while the game is live rather than something you reproduce from a log. The README points at BasicInkExampleEditor.cs in the Basic Demo for how to do that, showing an attach and detach button on an inspector and automatic attachment on entering play mode. More detail is in the Ink Player Window documentation in the repository. The Inspector is the quieter half of the toolchain. Selecting an ink file shows compile errors, warnings and TODOs, and maps out the include hierarchy, so you can see at a glance whether a file is a master or an include, and which files it includes or is included by.

The WebGL build carries the compiler unless you split the assembly

This is the limitation that will cost you build size, and the README has a section for it. 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. The fix is a project change rather than a setting: split the compiler, InkLibs/InkCompiler, into its own editor-only assembly definition so it is stripped from builds, and you also need the editor assembly to reference that new assembly. The runtime, InkLibs/InkRuntime, never needs the compiler, so the split is clean. If you do need to compile ink at runtime, say to build dialogue from data, you keep the compiler in and accept the size. The second constraint is the editor version. Ink for Unity 2.0 supports Unity 2022.3 LTS and above, while the 1.x line supports 2020 LTS and above, so a project still on 2020 LTS has to stay on the older line or upgrade the editor. The Linux Unity Editor is supported, and the README answers that question with a single word.

How this compares to running the ink compiler yourself

There are three other ways to get ink into a Unity project, and the differences show up in the day to day rather than in the feature list. The first is to run the ink compiler as an external step, produce a .json file per story, import that as a TextAsset and load it at runtime. You keep full control of when compilation happens and what goes into version control, and you take on the job of making sure the JSON matches the .ink file, which is exactly the failure mode the ScriptedImporter exists to remove. The second is to embed the ink runtime yourself in the project, compiling the C# sources directly, which gives you a runtime without the editor tooling: no Ink Player Window, no inspector integration, and no automatic compilation, so you have built the first option with more manual work. The third is to avoid ink for short or fixed text and use Unity's own string tables or a simpler dialogue asset, which is less machinery when the narrative does not branch. The package's approach sits between the first and the second. It gives up the explicit compile step and the JSON artefact in exchange for the Ink Player Window, live variable editing, and an inspector that shows compile errors where you wrote the story. If your writers are not the ones editing .ink files in Unity, that advantage shrinks and the first option becomes competitive again.

Editorial conclusion

ink-unity-integration is the right choice for a Unity project that ships branching narrative and wants the writer's file to be the single source of truth with no separate compile step, because the ScriptedImporter model removes the .json file that usually has to be regenerated and kept in version control. It is the wrong choice for a project that only needs a fixed set of text screens, and it is a poor fit for a WebGL build where binary size matters and you never compile at runtime, since the compiler ships inside the Ink-Libraries assembly by default. Before you adopt it, read the WebGL best practices section and decide whether you will split InkLibs/InkCompiler into an editor-only assembly definition, and confirm the editor version, because 2.0 supports Unity 2022.3 LTS and above while the 1.x line supported 2020 LTS and above.

Frequently asked questions

Official sources

1. inkle/ink-unity-integration on GitHub
2. Issues
3. Project website
4. README
5. Releases