| Name | inkcpp-py JSON |
| Version |
0.1.6
JSON |
| download |
| home_page | None |
| Summary | Python bindings for InkCPP a Inkle runtime written in C++ |
| upload_time | 2024-04-24 15:56:03 |
| maintainer | None |
| docs_url | None |
| author | Julian Benda |
| requires_python | >=3.7 |
| license | MIT License Copyright (c) 2024 Julian Benda Copyright (c) 2020 Brook Jensen Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
ink
inkpp
inklecate
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# inkcpp
Inkle Ink C++ Runtime with JSON -> Binary Compiler.
Ink Proofing Test Results: https://jbenda.github.io/inkcpp/proof
Doxygen Documentation: https://jbenda.github.io/inkcpp/html
## Project Goals
* Fast, simple, clean syntax
* No heap allocations during execution (unless in emergencies)
* No external dependencies, but extensions available for `Unreal` and `STL` 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
## 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](https://github.com/inkle/ink/releases) 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](https://github.com/chromy/ink-proof).
In addition a UE Plugin inclusive BluePrints are provided and python bindings based on [pybind11](https://github.com/pybind/pybind11).
KeyFeatures: snapshots, observers, binding ink functions, support ink [function fallback](https://github.com/inkle/ink/blob/master/Documentation/RunningYourInk.md#fallbacks-for-external-functions)
## Unreal Plugin
InkCPP is available via the [UE Marketplace](https://www.unrealengine.com/marketplace/product/inkcpp).
Alternativly is the latest version of the UE plugin can be downloaded from the [release page](https://github.com/JBenda/inkcpp/releases/latest) (`unreal.zip`).
Place the content of this file at your plugin folder of your UE project and at the next start up it will be intigrated.
A example project can be found [here](https://jbenda.github.io/inkcpp/unreal/InkCPP_DEMO.zip). And here the [Documentation](https://jbenda.github.io/inkcpp/html/group__unreal.html).
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.).
If you compile the UE Plugin by your self feel free to visit the [wiki page](https://github.com/JBenda/inkcpp/wiki/Unreal) for a more debug oriented build process.
## Use standalone
1. Grep the current version from the [release page](https://github.com/JBenda/inkcpp/releases/latest) depending on your OS (e.g. macos-cl).
2. unpack it to a location found by your path
3. run your story: `inkcpp-cl -p story.json`
4. if you want to compile `.ink` flies directly make sure `inklecate` is in your path. If you not have it you can grep it from the [official page](https://github.com/inkle/ink/releases/latest)
Nice features for testing:
+ predefined choice selection `echo 1 2 1 | inkpp-cl -p story.(ink|json|bin)`
+ create snapshots to shorten testing:
+ create snapshot by entering `-1` as choice `echo 1 2 -1 | inkcpp-cl -p story.ink`
+ load snapshot as an additional argument `echo 1 | inkcpp-cl -p story.snap story.ink`
## Including in C++ Code
Instructions:
1. Download the for your OS macthing lib archive from the [release page](https://github.com/JBenda/inkcpp/releases/latest) (e.g. linux-lib).
2. 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` and `lib/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.
5. Reference the headers in your code like so:
```cpp
#include <ink/story.h>
#include <ink/runner.h>
#include <ink/choice.h>
```
6. if you use cmake checkout the (wiki)[https://github.com/JBenda/inkcpp/wiki/building#cmake-example] for including the library via cmake
### Example
```cpp
#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);
```
## Configuring and Building (CMake)
To configure the project...
1. Install CMake
2. Create a folder called `build`
3. 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.
To install the different components use `cmake --install . --component <lib|cl|unreal>`
+ `lib` C++ library to link against
+ `cl` command line application
+ `unreal` UE-plugin
For a more in depth installation description please checkout the [wiki](https://github.com/JBenda/inkcpp/wiki/building).
### 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.
## Python Bindings
The easy way to start is installing it with pip: `pip install inkcpp_py`.
An example can be found at [example.py](./inkcpp_py/example.py).
To build it from source use:
```sh
git clone --recurse-submodules https://github.com/JBenda/inkcpp.git
pip install inkcpp
```
The python bindnigs are defined in `inkcpp_py` subfolder.
## 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "inkcpp-py",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "ink, inkpp, inklecate",
"author": "Julian Benda",
"author_email": "julian.benda@ovgu.de",
"download_url": "https://files.pythonhosted.org/packages/45/66/979452118dc492a7306d4473b1438c3a5bd89bac316dd37674203f152739/inkcpp_py-0.1.6.tar.gz",
"platform": null,
"description": "# inkcpp\n![build](https://github.com/JBenda/inkcpp/workflows/build/badge.svg \"Build Status\")\n\nInkle Ink C++ Runtime with JSON -> Binary Compiler.\n\nInk Proofing Test Results: https://jbenda.github.io/inkcpp/proof\n\nDoxygen Documentation: https://jbenda.github.io/inkcpp/html\n\n## Project Goals\n* Fast, simple, clean syntax\n* No heap allocations during execution (unless in emergencies)\n* No external dependencies, but extensions available for `Unreal` and `STL` by opt-in preprocessor defines\n* 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.)\n* Multi-thread safe\n\n\n## Current Status\n\nRun `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.\n`inklecate` can be downloaded from the [official release page](https://github.com/inkle/ink/releases) and will be downloaded from CMake at configure time (located at `build/unreal/inkcpp/Resources/inklecate`).\n\nWithout the `-p` flag, it'll just compile the JSON/Ink file into InkCPP's binary format (see the Wiki on GitHub).\n\nAll features of ink 1.1 are supported, and checked with [ink-proof](https://github.com/chromy/ink-proof).\n\nIn addition a UE Plugin inclusive BluePrints are provided and python bindings based on [pybind11](https://github.com/pybind/pybind11).\n\nKeyFeatures: snapshots, observers, binding ink functions, support ink [function fallback](https://github.com/inkle/ink/blob/master/Documentation/RunningYourInk.md#fallbacks-for-external-functions)\n\n## Unreal Plugin\n\nInkCPP is available via the [UE Marketplace](https://www.unrealengine.com/marketplace/product/inkcpp).\n\nAlternativly is the latest version of the UE plugin can be downloaded from the [release page](https://github.com/JBenda/inkcpp/releases/latest) (`unreal.zip`).\nPlace the content of this file at your plugin folder of your UE project and at the next start up it will be intigrated.\n\n\nA example project can be found [here](https://jbenda.github.io/inkcpp/unreal/InkCPP_DEMO.zip). And here the [Documentation](https://jbenda.github.io/inkcpp/html/group__unreal.html). \n\nCode 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.).\n\nIf you compile the UE Plugin by your self feel free to visit the [wiki page](https://github.com/JBenda/inkcpp/wiki/Unreal) for a more debug oriented build process.\n\n## Use standalone\n\n1. Grep the current version from the [release page](https://github.com/JBenda/inkcpp/releases/latest) depending on your OS (e.g. macos-cl).\n2. unpack it to a location found by your path\n3. run your story: `inkcpp-cl -p story.json`\n4. if you want to compile `.ink` flies directly make sure `inklecate` is in your path. If you not have it you can grep it from the [official page](https://github.com/inkle/ink/releases/latest)\n\nNice features for testing:\n+ predefined choice selection `echo 1 2 1 | inkpp-cl -p story.(ink|json|bin)`\n+ create snapshots to shorten testing:\n\t+ create snapshot by entering `-1` as choice `echo 1 2 -1 | inkcpp-cl -p story.ink`\n \t+ load snapshot as an additional argument `echo 1 | inkcpp-cl -p story.snap story.ink`\n\n## Including in C++ Code\n\nInstructions:\n\n1. Download the for your OS macthing lib archive from the [release page](https://github.com/JBenda/inkcpp/releases/latest) (e.g. linux-lib).\n2. The following must be linked into your build solution for your C++ to compile correctly:\n\t- `include/ink`: contains important shared headers.\n\t\t+ For a Visual Studio project, link this directory as an Include Directory in VC++ Directories.\n\t- `lib/inkcpp.lib` and `lib/inkcpp_compiler.lib`: contains the library code for the InkCPP runner and compiler, respectively.\n\t\t+ For a Visual Studio project, link these files as Additional Dependencies in Linker->Input.\n\t\t+ You don't need to link the compiler if you're not using it within your program.\n5. Reference the headers in your code like so:\n```cpp\n\n#include <ink/story.h>\n#include <ink/runner.h>\n#include <ink/choice.h>\n```\n6. if you use cmake checkout the (wiki)[https://github.com/JBenda/inkcpp/wiki/building#cmake-example] for including the library via cmake\n\n\n### Example\n\n```cpp\n#include <ink/story.h>\n#include <ink/runner.h>\n#include <ink/choice.h>\n\nusing namespace ink::runtime;\n\nint MyInkFunction(int a, int b) { return a + b; }\n\n...\n\n// Load ink binary story, generated from the inkCPP compiler\nstory* myInk = story::from_file(\"test.bin\");\n\n// Create a new thread\nrunner thread = myInk->new_runner();\n\n// Register external functions (glue automatically generated via templates)\nthread->bind(\"my_ink_function\", &MyInkFunction);\n\n// Write to cout\nwhile(thread->can_continue())\n\tstd::cout << thread->getline();\n\n// Iterate choices\nfor(const choice& c : *thread) {\n\tstd::cout << \"* \" << c.text() << std::endl;\n}\n\n// Pick the first choice\nthread->choose(0);\n\n```\n\n\n## Configuring and Building (CMake)\n\nTo configure the project...\n\n1. Install CMake\n2. Create a folder called `build`\n3. From the build folder, run `cmake ..`\n\nCMake 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.\n\nThe documentation can be build iff Doxygen is installed with `cmake --build . --target doc`. The documentation can then be found in at `html/index.html`.\n\nTo 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.\n\nTo install the different components use `cmake --install . --component <lib|cl|unreal>`\n+ `lib` C++ library to link against\n+ `cl` command line application\n+ `unreal` UE-plugin\n\nFor a more in depth installation description please checkout the [wiki](https://github.com/JBenda/inkcpp/wiki/building).\n\n\n### Troubleshooting\n\nIf 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.\n\n\n### Running Tests\n\nRun `ctest` from the build folder to execute unit tests configured with CMake. Use `ctest -V` for more verbose error output.\n\nRight 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.\n\n\n## Python Bindings\n\nThe easy way to start is installing it with pip: `pip install inkcpp_py`.\nAn example can be found at [example.py](./inkcpp_py/example.py).\nTo build it from source use:\n\n```sh\ngit clone --recurse-submodules https://github.com/JBenda/inkcpp.git\npip install inkcpp\n```\n\nThe python bindnigs are defined in `inkcpp_py` subfolder.\n\n## Dependencies\nThe compiler depends on Nlohmann's JSON library and the C++ STL.\n\nThe 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. \n\nNOTE: 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.\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 Julian Benda Copyright (c) 2020 Brook Jensen Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Python bindings for InkCPP a Inkle runtime written in C++",
"version": "0.1.6",
"project_urls": {
"Issues": "https://github.com/JBenda/inkcpp/issues",
"Repository": "https://github.com/JBenda/inkcpp.git"
},
"split_keywords": [
"ink",
" inkpp",
" inklecate"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4566979452118dc492a7306d4473b1438c3a5bd89bac316dd37674203f152739",
"md5": "668c00bca8f16254af64dcd214132ff0",
"sha256": "ac4cbd842a3e195476bf2b898c00bc0bc2b46169c66b285f51871fc949085728"
},
"downloads": -1,
"filename": "inkcpp_py-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "668c00bca8f16254af64dcd214132ff0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 1023301,
"upload_time": "2024-04-24T15:56:03",
"upload_time_iso_8601": "2024-04-24T15:56:03.096326Z",
"url": "https://files.pythonhosted.org/packages/45/66/979452118dc492a7306d4473b1438c3a5bd89bac316dd37674203f152739/inkcpp_py-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-24 15:56:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JBenda",
"github_project": "inkcpp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "inkcpp-py"
}
