Inkle Ink C++ Runtime with JSON -> Binary Compiler.
Ink Proofing Test Results: https://brwarner.github.io/inkcpp
- Fast, simple, clean syntax
- No heap allocations during execution (unless in emergencies)
- No external dependencies, but extensions available for
Unreal
andSTL
by opt-in preprocessor defines - Support for multiple "runners" (not ink threads) running in parallel on a single story that can optionally share a global variable/state store (but with their own callstack, temporaries, etc.)
- Multi-thread safe
#include <ink/story.h>
#include <ink/runner.h>
#include <ink/choice.h>
using namespace ink::runtime;
int MyInkFunction(int a, int b) { return a + b; }
...
// Load ink binary story, generated from the inkCPP compiler
story* myInk = story::from_file("test.bin");
// Create a new thread
runner thread = myInk->new_runner();
// Register external functions (glue automatically generated via templates)
thread->bind("my_ink_function", &MyInkFunction);
// Write to cout
while(thread->can_continue())
std::cout << thread->getline();
// Iterate choices
for(const choice& c : *thread) {
std::cout << "* " << c.text() << std::endl;
}
// Pick the first choice
thread->choose(0);
Run inkcpp_cl.exe -p myfile.json
to execute a compiled Ink JSON file in play mode. It can also operate on .ink
files but inklecate.exe
must me in the same folder or in the PATH.
Without the -p
flag, it'll just compile the JSON/Ink file into InkCPP's binary format (see the Wiki on GitHub).
Many, but not all features of the Ink language are supported (see Glaring Omissions below), but be warned, this runtime is still highly unstable. I am currently working on getting it to pass all the unit tests on ink-proof.
- Temporary and global variables
- Int, String, or Divert values
- Eval stack (
ev
,/ev
), String stack (str
,/str
) - Choices (support for both
*
and+
and conditional choices) - Diverts (variable and fixed, conditional and normal)
- All mathematical operators (
+
,<=
, etc.). String equality not supported. - Glue
- Visit and read counts (
visits
andCNT?
commands). seq
command and all sequence types (stopping, cycle, shuffle)- Global store that can be shared between runners
- External function binding (no fallback support yet)
- Tunnels and internal functions
- Ink threads (probably incredibly unstable though)
To configure the project...
- Install CMake
- Create a folder called
build
- From the build folder, run
cmake ..
CMake will then generate the necessary build files for your environment. By default, it generates Visual Studio projects and solutions on Windows and Makefiles on Mac and Linux. You can change this using CMake's command line options (see cmake --help
). It supports pretty much anything.
To build, either run the generated buildfiles OR you can use cmake --build . --config <Release|Debug>
from the build folder to automatically execute the relevant toolchain.
For a more in depth installation description please checkout the (wiki)[https://github.com/brwarner/inkcpp/wiki/building].
Required software: (CMake)[https://cmake.org/]
Instructions:
- Clone the repository
- Configure and build the project with CMake, as described above
- From your newly-created
build
directory, runcmake --install . --prefix Path/To/Desired/Library/Directory --component <lib/cl/unreal>
. - Generated in your chosen directory, you will find a collection of folders. The following must be linked into your build solution for your C++ to compile correctly:
include/ink
: contains important shared headers.- For a Visual Studio project, link this directory as an Include Directory in VC++ Directories.
lib/inkcpp.lib
andlib/inkcpp_compiler.lib
: contains the library code for the InkCPP runner and compiler, respectively.- For a Visual Studio project, link these files as Additional Dependencies in Linker->Input.
- You don't need to link the compiler if you're not using it within your program.
- if you used the
cl
component you will find theinkcpp_cl
executable in this location - for
unreal
you will find aSource
directory containing the Unreal needed libs and headers. Note: not working for the current unreal version, we are working to fix this.
- Reference the headers in your code like so:
#include <ink/story.h>
#include <ink/runner.h>
#include <ink/choice.h>
- if you use cmake checkout the (wiki)[https://github.com/brwarner/inkcpp/wiki/building#cmake-example] for including the library via cmake
If you recieve an error like "Mismatch Detected for Runtime Library," it means you are probably using the Release version of the .lib
files, but are running under a Debug configuration. To fix this, you can manually copy the .lib
and .pdb
files from build/inkcpp/Debug
and/or build/inkcpp_compiler/Debug
after running the build process again with --config Debug
(see above). Then, you can add separate Debug and Release directories in the installed package folder, and change the paths based on your selected configuration in Visual Studio or otherwise, so that it links the Debug .lib
for the Debug build, and the Release .lib
for the Release build.
Run ctest
from the build folder to execute unit tests configured with CMake. Use ctest -V
for more verbose error output.
Right now this only executes the internal unit tests which test the functions of particular classes. Soon it'll run more complex tests on .ink files using ink-proof.
Code for the Unreal plugin is located in the unreal
directory. In order to install it, run cmake --install . --component unreal --prefix Path/To/Unreal/Plugins/
which will add an inkcpp
folder there with the .uplugin
, the code for the UClasses, and all the inkcpp source files required. config.h
will automatically detect it is being built in an Unreal plugin environment and disable STL and enable Unreal extensions (FString support, Unreal asserts, CityHash, etc.).
I am currently working toward a 1.0 release. You can track my progress here: https://github.com/brwarner/inkcpp/projects/1
The big things we're missing right now are:
- Fallback functions for externals.
- Variable observers
- Lists and whatever cool, crazy stuff Ink has been adding recently.
- Robust tests using ink-proof.
The compiler depends on Nlohmann's JSON library and the C++ STL.
The runtime does not depend on either. If INK_ENABLE_STL
is defined then STL extensions are added such as stream operators and std::string
support. If INK_ENABLE_UNREAL
, then FStrings, Delegates and other Unreal classes will be supported.
NOTE: There is still some lingering C standard library calls in the runtime. I will be guarding them with an INK_ENABLE_CSTD
or something soon.