InkCPP Documentation

Table of Contents

• CMAKE usage
  • CMake Flags
  • main.cpp
  • CMakeLists.txt
  • test.ink
• Unreal Installation
• Python example

Inkle Ink C++ Runtime with INK.JSON -> Binary Compiler.
supports ussage in:

• C++ (with CMAKE)
• UE
• Python inkcpp_py

CMAKE usage

The current erlease is available at the release page, as <os>-lib.zip (e.g. linux-lib.zip).
to link the libraries you can use find_package(inkcpp CONFIG) which provides two targets:

• inkcpp: the runtime enviroment
• inkcpp_compiler: functionality to compile a story.json to story.bin

To run your own .ink files you need a way to compile it to inks runtime format .ink.json. One way is to use inklecate <story>.ink.
Which is available at the official release page.
Alternativly set the enviroment variable INKLECATE so that INKLECATE% executes inklecate.

If you want to use the inkcpp with C link against the target inkcpp_c and #include <ink/c/inkcpp.h> The C-API documentation and example can be found here.

Exampl with library extracted at /YOUR/PROJECT/linux-lib And the Example project is extracted to /YOUR/PROJECT

cd /YOUR/PROJECT
ls # expected output: CMakeLists.txt main.cpp test.ink test.ink.json linux-lib
mkdir build
cd build
inkcpp_DIR=../linux-lib cmake .. -DCMAKE_BUILD_TYPE=Release  # linux
set inkcpp_DIR=../win64-lib                                  # windows
cmake ..                                                     # windows
cmake --build . --config=Release
cd ..
./build/main_cpp                                             # exact path depends on build system
used

CMake Flags

• INKCPP_TEST: (ON|OFF) weather or not execute tests requires inklecate to be in the PATH or INKCPP_INKLECATE=OS or =ALL
• INKCPP_INKLECATE: (NONE|OS|ALL) download the current supported inklecate version from the official release page
  They are stored at <build-dir>/inklecate/<os>/ and will be automatcilly used for the tests
  • NONE: disable this function
  • OS: only the version supported for the OS
  • ALL: all versions
• INKCPP_C: (ON|OFF) Build the inkcpp c bindings (and thest them if test is enabled)
• INKCPP_PY: (ON|OFF) Build python bindings (build system only)
• WHEEL_BUILD: (ON|OFF) Settings to work with a python wheel build (build system only)
• INKCPP_DOC_BlueprintUE: (ON|OFF) enables nice blueprint renders for the documentation

main.cpp

#include <ink/system.h>
#include <ink/choice.h>
#include <ink/runner.h>
#include <ink/story.h>
#include <ink/compiler.h>
 
#include <iostream>
 
using namespace ink::runtime;
 
int MyInkFunction(int a, int b) { return a + b; }
 
int main()
{
    ink::compiler::run("test.ink.json", "test.bin");
    // 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
    int id = 0;
    for (const choice& c : *thread) {
        std::cout << (id++) << ". " << c.text() << std::endl;
    }
    std::cin >> id;
    thread->choose(id);
 
    // Write to cout
    while (thread->can_continue())
        std::cout << thread->getline();
}

CMakeLists.txt

cmake_minimum_required(VERSION 3.16)
project(main)
 
find_package(inkcpp CONFIG REQUIRED)
 
# for CXX builds
add_executable(main_cpp main.cpp)
set_property(TARGET main_cpp PROPERTY CXX_STANDARD 20)
target_link_libraries(main_cpp inkcpp inkcpp_compiler)
 
# for C builds
# add_executable(main_c main.c)
# target_link_libraries(main_c inkcpp_c)

test.ink

EXTERNAL my_ink_function(a,b)
 
Hello world!
*   Hello back!
    Nice to hear from you!
*   Bye
    BTW 3 + 5 = {my_ink_function(3,5)}
-> END

compiled: test.ink.json

Unreal Installation

The easiest way is to install it via the unreal marcetplace. The overview to the UE Blueprint class and examples can be found at here.

The current release is also available at the release page, as unreal.zip.
Unpack this foldor in /PATH/TO/UNREAL_ENGINE/Engine/Plugins/ and it will be available as plugin in the plugin list.
Or unpack this folder in /PATH/TO/UNREAL_PROJECT/Plugins/ and it will be intigrated at the next startup.
A MarketPlace appearance is work in progress :)

If you want to use the newest version clone the project and install the unreal component.

git clone https://github.com/JBenda/inkcpp
cd inkcpp
mkdir build
mkdir plugin
cd build
cmake ..
cmake --install . --component unreal --prefix ../plugin
cd ../plugin
# Should contain a folder named 'inkcpp'
cp -r inkcpp /PATH/TO/UNREAL_PROJECT/Plugins

Python example

You can install the current release from pypi with
pip install inkcpp-py.
Or build it yourself from main with:
pip install .

Here can you find an example inclusive story.

Python module documentation