inkcpp
Inkle Ink C++ Runtime with JSON -> Binary Compiler.
Ink Proofing Test Results: https://brwarner.github.io/inkcpp
Project Goals
- 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
Example
#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);
Current Status
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 be in the same folder or in the PATH.
inklecate
can be downloaded from the official release page and will be downloaded from CMake at configure time (located at build/unreal/inkcpp/Resources/inklecate
).
Without the -p
flag, it'll just compile the JSON/Ink file into InkCPP's binary format (see the Wiki on GitHub).
All features of ink 1.1 are supported, and checked with ink-proof.
Big features missing compared to the C#
implementation are:
- stable Ink Thread support
Configuring and Building (CMake)
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.
The documentation can be build iff Doxygen is installed with cmake --build . --target doc
. The documentation can then be found in at html/index.html
.
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].
Including in C++ Code
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
Troubleshooting
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.
Running Tests
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.
Unreal Plugin
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.).
Next Steps
I am currently working toward a 1.0 release. You can track my progress here: https://github.com/brwarner/inkcpp/projects/1
Dependencies
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.