davidcolson / unrealink

Integration of the Ink language into Unreal 4 (https://github.com/inkle/ink)

Unreal Ink

This is a plugin allowing you to use the excellent dynamic narrative scripting system, Ink, in Unreal Engine. Visit the Ink repository for more information on it. The plugin still is ostensibly finished. All of the features of the C# API are available except for the profiler, which isn't hugely important. Also the ink runtime itself is up to date and fully featured. Please don't hesistate to contact me for any problems or help you need. I live at @dave_colson on twitter and you can email me at [email protected].

As of current master branch, compatible with Ink 0.9.0.

How to use

I have provided packaged versions of the plugin, complete with the example project. I try keep it updated for the most recent versions of Unreal, if it's not updated poke me and I can do it for you. Simply drop the packaged plugin into the plugins folder of your engine or game. Once loaded it into your project, you can use the plugin either through C++ or more easily through blueprints. First though we need to go over importing Ink assets.

Importing Ink Assets

The plugin provides a new asset that represents ink stories (UStoryAsset). You can import plain .ink files and the plugin will automatically compile them for you. This way you can set up auto-reimporting of the ink files which will be recompiled on import. Simply import the .ink file as you would any other file.

Use through blueprints

After importing your .ink file, you can create a new story node and select your story asset in the dropdown.

This will return a story instance, which can then be used just like as is shown in the inkle documentation files. The idea is that there's a node for every function available in the Ink API, though a few are missing.

I have provided an example project demonstrating a basic usage of the system, which only uses blueprints, so go check that out.

Use through C++

It's very similar to the blueprints here as well. Load a story asset file, call UStory::NewStory(); and then all existing function calls are basically the same as in the Inkle library, with a couple of exceptions (variadic functions). I will provide an example of this soon. For now take a look at the Story.h file for a list of possible function calls.

How does it work?

It works by embedding the Mono runtime directly into the plugin in Unreal, and then has a special C# assembly called InkGlue, which marshalls data and function calls between C# and C++ to lessen the amount of complicated binding code present in C++. It requires linking with mono, and since I've only got a windows PC currently I've provided the windows mono library. Theoretically it'll work fine on Mac, you just need to link the mono-sgen dynlib.

Platform support

• Windows - First class support
• Mac - I have setup the build scripts to support Mac, and I've provided the third party dlls so that it'll work, but I don't have a Mac so this is untested. Seeking people with a Mac to help me test this
• Consoles - Mono is stated to work on PS4 and Xbox One/Series X but I have no access to dev kits so I cannot test this. Theoretically it would just involve linking the appropriate mono library, and including matching core assemblies that you've compiled with mono.

unrealink's Issues

Non-latin characters are broken!

Cyrillic characters are displayed as questions. I tried both source .ink file is in UTF-8 and Windows-1252 encodings.

Can't load included ink files

I'm doing something with a lot of dynamically triggered narrative events rather than one big story, so I figured that I could keep the structure clean by putting each event in its own included ink file. However, the plugin won't load these files properly:

Asset re-importing does not work

When dragging an ink file to the editor for the very first time, everything works great - a UStoryAsset file is created properly.
When modifiying the source ink file afterwards, Unreal does show a notification that is is processing resources, but the asset factory create file method is not called, and the UStoryAsset is not updated.

Plugin crashes

Hi David,
thanks a lot for this plugin. I am encountering infrequent desktop crashes originating in the plugin.
The crashes are in UStory::ChoosePathString while invoking MonoInvoke:

inline void MonoInvoke<void>(FString MethodName, void** params)
{
	FInkModule& Ink = FModuleManager::GetModuleChecked<FInkModule>("Ink");

	MonoObject* Exception;
	mono_runtime_invoke(Methods[MethodName], Instance, params, &Exception);
	Ink.MaybeThrowMonoException(Exception);
}

I was trying to track down the crash and eventually, it leads me to think that it might be UE4 Garbage Collector, collecting
probably(?) TMap, which is not marked as UPROPERTY() This would explain to me the randomness in which the class crashes.

I was going through the Minidump, but couldn't pinpoint the issue better than this.

Any idea, if Methods could be marked for non-deletion or UPROPERTized?

I thought of wrapping MonoMethod into USTRUCT so it could be markable, but I am not sure if this would be the right way.

Thanks,
Jan

Non latin characters broken

How to reproduce:
Create simple project

1. Add stort with non latin (for example cyrillic) story.
2. Display story with any way( UE_LOG macro, widget, etc)
3. Characters are displays as question marks

UE4 "UnrealInk" is Incompatible 4.27.2

Hi all,
I am currently having an issue integrating the plugin for ink into Unreal 4.27.2
Whenever I try to start the engine after dragging the plugins folder into my files (see images below) I receive the following errors before the engine does not start and requests I manually rebuild from source.

Any help would be greatly appreciated.
Kind regards
Chris

Update for Unreal Engine 5 Launch

Hello, you mentioned in the readme to drop you a line if the plugin hadn't been updated for the latest UE release. I'd love to use Ink in a new UE5 project and would be glad to get involved in any way I can to help get this up to UE5 compatability. You also mention that you're looking for someone to confirm Mac compatability - I'd love to get involved with that too if I may.

Android compatibility

I looked up mono library and it states it's been ported to Android. Does this plugin support Android builds?

Engine crashes with multiple Story objects in memory!

I'm using an Array of Story objects. One Story for each NPC in my game. Each Story initialization takes place only when I'm starting my conversation with next NPC. But when I'm returning to the previous NPC (switching the pointer of the Story Array to the previous array index) - the Engine crashes with Unhandled Exception: EXCEPTION_ACCESS_VIOLATION reading address 0x0000000000000000

mono_2_0_sgen
UE4Editor_Ink!UMonoBaseClass::MonoInvoke<bool>() [d:\unreal\exampleprojects\blank\plugins\unrealink\source\ink\private\monobaseclass.h:47]
UE4Editor_Ink!UStory::CanContinue() [d:\unreal\exampleprojects\blank\plugins\unrealink\source\ink\private\story.cpp:121]
UE4Editor_Ink!UStory::execCanContinue() [d:\unreal\exampleprojects\blank\plugins\unrealink\intermediate\build\win64\ue4editor\inc\ink\story.gen.cpp:281]
UE4Editor_CoreUObject
UE4Editor_CoreUObject
...

Is there any way to manage more than one Story object at the same time?

Some types of hyphens are being output as question marks

Becomes

The problem is the special hyphens. If I replace them with typed hyphens on my keyboard, the scene displays properly. Is it unicode?

unreal 4.26, using the example project with TheIntercept after selecting 'plan'

CurrentPathString always Returns Empty String

I've tried using the CurrentPathString node, but always get an empty string. I've tried it on multiple stories in multiple locations, but always get an empty string.

Windows-64 packaging fails: "Missing precompiled manifest" (UE 4.26.2)

Thanks for making a great plugin! I'm trying to package for Windows-64 in UE 4.26.2 (shipping configuration), and getting this error:
ERROR: Missing precompiled manifest for 'Ink'. This module was most likely not flagged for being included in a precompiled build - set 'PrecompileForTargets = PrecompileTargetsType.Any;' in Ink.build.cs to override.

It's been awhile since I've used Unreal, so apologies if this is a basic question, but do I need to create an Ink.build.cs file? I couldn't find one in the repo.

Cannot open include file monobaseclass UE5.1

 D:\GameDev\UnrealProjects\Psionic\Plugins\UnrealInk\Source\Ink\Public\Story.h(6): fatal error C1083: Cannot open include file: 'MonoBaseClass.h': No such file or directory
Build failed.

Hi, currently trying to access the c++ api. Everything seems to work fine using it from blueprints and accessing a story, but when trying to add the c++ API, i'm unable to compile after doing

#include "Story.h

I added Ink to my build.cs as such:

		PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "EnhancedInput", "Paper2D", "Ink" });

If anyone has any advice on how I can work through this, greatly appreciated. I'm needing the c++ API to use ink EXTERNAL functions. :)

When building does mono get bundled with the build?

A little bit green to this, but I was wondering since there is a mono dependency here, is that dependency still present in the final build of a game or is it only present when developing?

Thanks for any help!

Can't load Cyrillic Characters

I can put Cyrillic and other non-ASCII characters in .ink files, but they show up only as question marks in Unreal.

Packaged build crashes on startup

So this happens when I try to run a packaged build, the above screenshot is from a completely unaltered exampled project in 4.26.1. Not sure if it's a bug or I'm missing some step in the packaging process?

“Choose Path String” seems not to work

I’m working on a project that needs extensive use of the Choose Path String feature. I made a know and called that function with the name of the knot as its argument and the story did not change. To be completely honest, I did not try this in InkJS, but the definition of the method seems pretty straightforward. Is there a known problem with this method?

Thanks.

Project not working on Mac

I've using the plugin in Windows and it works fine but I wanted to create a build in Mac and I'm having issues.

The first time I open the UnrealInkExample project it says that the plugin has to be compiled and I don't see any errors after that so I assume it compiles the plugin fine. I can also see here the file you mention in Readme

But when I run the game or opening the blueprints I see compiler errors

And if I refresh the node I see this

I don't know very much where to look to check if the compilation has been working fine or how to link the library properly.

Another thing I tried is adding "Mac" to both "WhitelistPlatforms" at UnrealInk.uplugin and after that when I try to open the project this is what happens:

Any idea how can I make this work? Thank you very much!

How can I use 4.27 plugin in 4.26 Engine?

Hi!
My project now is totally in UE 4.26 and it depends on many other plugins without 4.27 support.
How can I get UnrealInk with unicode support for 4.26? Unicode support is critical for my project.