{"id":13661670,"url":"https://github.com/y-lohse/inkjs","last_synced_at":"2026-01-11T23:04:36.699Z","repository":{"id":37271208,"uuid":"59676058","full_name":"y-lohse/inkjs","owner":"y-lohse","description":"A javascript port of inkle's ink scripting language.","archived":false,"fork":false,"pushed_at":"2025-04-11T19:51:05.000Z","size":13917,"stargazers_count":543,"open_issues_count":10,"forks_count":108,"subscribers_count":27,"default_branch":"master","last_synced_at":"2025-04-19T01:27:41.257Z","etag":null,"topics":["game-development","inkjs","story"],"latest_commit_sha":null,"homepage":"http://www.inklestudios.com/ink/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/y-lohse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-05-25T15:40:56.000Z","updated_at":"2025-04-18T16:05:56.000Z","dependencies_parsed_at":"2023-09-27T16:09:31.032Z","dependency_job_id":"ee4f9839-63c8-453f-aafb-bc414aef6759","html_url":"https://github.com/y-lohse/inkjs","commit_stats":null,"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y-lohse%2Finkjs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y-lohse%2Finkjs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y-lohse%2Finkjs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y-lohse%2Finkjs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/y-lohse","download_url":"https://codeload.github.com/y-lohse/inkjs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250747675,"owners_count":21480691,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["game-development","inkjs","story"],"created_at":"2024-08-02T05:01:39.181Z","updated_at":"2026-01-11T23:04:36.693Z","avatar_url":"https://github.com/y-lohse.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# ![inkjs](media/inkjs.png)\n\n![build](https://github.com/y-lohse/inkjs/workflows/Build/badge.svg)\n[![npm](https://img.shields.io/npm/v/inkjs.svg)](https://www.npmjs.com/package/inkjs)\n[![codecov](https://codecov.io/gh/y-lohse/inkjs/branch/master/graph/badge.svg)](https://codecov.io/gh/y-lohse/inkjs)\n\nThis is a javascript port of inkle's [ink](https://github.com/inkle/ink), a scripting language for writing interactive narrative.\n\ninkjs is fully compatible with the original version, has zero dependency and works in all browsers and node.js. Please have a look at [the demo](http://yannick-lohse.fr/inkjs/)!\n\n## Table of content\n\n- [](#)\n\t- [Table of content](#table-of-content)\n\t- [Installation](#installation)\n\t- [Quickstart](#quickstart)\n\t- [Working with a JSON file](#working-with-a-json-file)\n\t- [Using node.js](#using-nodejs)\n\t\t- [Loading inkjs](#loading-inkjs)\n\t\t- [Loading a json file](#loading-a-json-file)\n\t\t- [Starting a story](#starting-a-story)\n\t- [Differences with the C# API](#differences-with-the-c-api)\n\t\t- [Getting and setting ink variables](#getting-and-setting-ink-variables)\n\t\t- [Getting the output text when calling `EvaluateFunction`](#getting-the-output-text-when-calling-evaluatefunction)\n\t- [Using TypeScript](#using-typescript)\n\t- [Compiler](#compiler)\n\t\t- [inkjs-compiler.js](#inkjs-compilerjs)\n\t\t- [online compiler](#online-compiler)\n\t\t- [Differences with the C# Compiler](#differences-with-the-c-compiler)\n\t- [Compatibility table](#compatibility-table)\n\n## Installation\n\nInstall using `npm install inkjs`.\n\nIf you are not using npm you can grab the latest release directly from [here](https://unpkg.com/inkjs). Simply include that file with a script tag and you'll be on your way!\n\nFor projects targeting older browsers that have no support for ES2015 features, a (heavier but) more backward compatible version is also exposed. Grab it by either:\n\n- `import ink from 'inkjs/dist/ink.js`\n- Directly downloading the file from [here](https://unpkg.com/inkjs@1.11.0/dist/ink.js)\n\n## Quickstart\n\nThe simplest way to get started with inkjs is to use the [serverless boilerplate](https://github.com/y-lohse/inkjs/blob/master/templates/browser_serverless/) in the [templates folder](https://github.com/y-lohse/inkjs/blob/master/templates/). Replace the placeholder story in `story.js` with your own and open `index.html`!\n\nHere's what happens behind the scenes: inkjs gives you access to a global object named `inkjs` which has a property called `Story`. This is the main class we interact with.\n\nWe simply create a new story by calling `var story = new inkjs.Story(storyContent);` — the variable `storyContent` is defined in the `story.js` file. After that, we can use `story.Continue()` and `story.currentChoices` as described in the [the official documentation](https://github.com/inkle/ink/blob/master/Documentation/RunningYourInk.md#getting-started-with-the-runtime-api).\n\n## Working with a JSON file\n\nIf you frequently need to update your story, pasting the content into `story.js` will probably get tedious. So another option is to dynamically load the JSON file for your story. Unfortunately, your browser won't let you do that because of [CORS policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS), which means you need a web server to do this. You could do this without much hassle with [node.js](https://www.npmjs.com/package/http-server) or [python](http://www.linuxjournal.com/content/tech-tip-really-simple-http-server-python) for example.\n\nOnce the server is running, use the [other boilerplate](https://github.com/y-lohse/inkjs/blob/master/templates/browser_with_server) and place your story content inside `story.json`. Behind the scenes, the only difference is that we load the JSON file via ajax before creating the story:\n\n```javascript\nfetch('story.json')\n\t.then(function (response) {\n\t\treturn response.text();\n\t})\n\t.then(function (storyContent) {\n\t\tstory = new inkjs.Story(storyContent);\n\t\tcontinueStory();\n\t});\n```\n\n## Using node.js\n\nYou can find some boilerplate code for node.js [here](https://github.com/y-lohse/inkjs/blob/master/templates/nodejs).\n\n### Loading inkjs\n\n#### require\n\nYou can require the module: \n```javascript \nvar Story = require('inkjs').Story;\n```\n\n#### import\nYou can use import style: \n```javascript\nimport { Story } from 'inkjs';\n```\n\n### Loading a json file\n\nYou can load the json file using a simple call to `require`:\n\n```javascript\nvar json = require('./ink_file.json');\n```\n\nYou can also load it using `fs`. In that case, please note that inklecate outputs a json file encoded **with** BOM, and node isn't very good at handling that.\n\n```javascript\nvar fs = require('fs');\nvar json = fs.readFileSync('./ink_file.json', 'UTF-8').replace(/^\\uFEFF/, ''); //strips the BOM\n```\n\n### Starting a story\n\nNow that you have a `Story` object and a json file, it's time to bring it all together:\n\n```javascript\nvar inkStory = new Story(json);\n\nconsole.log(inkStory.ContinueMaximally());\n//etc\n```\n\nFrom there on, you can follow [the official documentation](https://github.com/inkle/ink/blob/master/Documentation/RunningYourInk.md#getting-started-with-the-runtime-api).\n\n## Differences with the C# API\n\nThere are a few very minor API differences between ink C# and inkjs:\n\n### [Getting and setting ink variables](https://github.com/inkle/ink/blob/master/Documentation/RunningYourInk.md#settinggetting-ink-variables)\n\nOn platforms that do not support [ES2015 Proxies](https://kangax.github.io/compat-table/es6/) (basically node.js v5, IE 11, Safari 9 and everything below), you can't directly read and write variables to the story state. Instead you will have to use the `$` function:\n\n```javascript\n_inkStory.variablesState.$('player_health', 100);\n//instead of _inkStory.variablesState[\"player_health\"] = 100;\n\nvar health = _inkStory.variablesState.$('player_health');\n//instead of var health = _inkStory.variablesState[\"player_health\"];\n```\n\n### Getting the output text when calling `EvaluateFunction`\n\n`EvaluateFunction()` lets you evaluate an ink function from within your javascript. The \"normal\" call is the same than in C#:\n\n```javascript\nvar result = EvaluateFunction('my_ink_function', ['arg1', 'arg2']);\n//result is the return value of my_ink_function(\"arg1\", \"arg2\")\n```\n\nHowever, if you also wish to retrieve the text that `my_ink_function` output, you need to call it like this:\n\n```javascript\nvar result = EvaluateFunction('my_ink_function', ['arg1', 'arg2'], true);\n//now result is an object with two properties:\n// result.returned is the return value of my_ink_function(\"arg1\", \"arg2\")\n// result.output is the text that was written to the output while the function was evaluated\n```\n\n## Compiler\n\n### inkjs-compiler.js\n\n```shell\n$ node inkjs-compiler.js -h\n\nUsage: inkjs-compiler \u003coptions\u003e \u003cink or json file\u003e\n   -o \u003cfilename\u003e:   Output file name\n   -c:              Count all visits to knots, stitches and weave points, not\n                    just those referenced by TURNS_SINCE and read counts.\n   -p:              Play mode (automatic if a json file is passed as argument)\n   -s:              Print stats about story including word count in JSON format\n   -k:              Keep inklecate running in play mode even after story is complete\n\n```\n\nIf you install the package globally it is available as the `inkjs-compiler` command.  \nAlternatively, you can call it using `npx inkjs`\n\n### online compiler\n\n```javascript\nconst inkjs = require(\"inkjs/full\") //the `full` submodule contains the Compiler\nconst story = new inkjs.Compiler(`Hello World`).Compile();\n// story is an inkjs.Story that can be played right away\n\nconst jsonBytecode = story.ToJson();\n// the generated json can be further re-used\n```\n\nYou can use this in combination with [Webpack and TypeScript](docs/working-with-typescript-and-webpack.md).\n\n### Differences with the C# Compiler\n\nSee [Differences with the C# Compiler](docs/compiler-differences.md).\n\n## Using TypeScript\n\nInkjs is also packaged to be usable with typescript imports, the main classes (`Story`, `InkList`, `Compiler`) are available under the `/types`submodule.\n\n```ts\nimport { Story, Compiler } from 'inkjs/types'; // shortcut\n\nlet story: Story;\nlet compiler: Compiler;\n```\n\nIt is also possible to import deeply nested classes if needed\n\n```ts\nimport { Story } from 'inkjs/engine/Story';\nimport { Compiler } from 'inkjs/compiler/Compiler';\n\nimport { Choice } from 'inkjs/engine/Choice'\nimport { Identifier } from 'inkjs/compiler/Parser/ParsedHierarchy/Identifier';\n\n```\n\n## Compatibility table\n\n| _inklecate_ version | _inkjs_ version | _json_ version |\n| :-----------------: | :-------------: | :------------: |\n|    0.3.5 – 0.4.0    |  1.0.0 – 1.1.0  |       18       |\n|    0.4.1 – 0.5.0    |  1.1.1 – 1.1.3  |                |\n|        0.5.1        |      1.2.0      |                |\n|        0.6.0        |      1.3.0      |                |\n|        0.6.1        |  1.4.0 – 1.4.1  |                |\n|        0.6.2        |      1.4.2      |                |\n|        0.6.3        |      1.4.3      |                |\n|        0.6.4        |  1.4.4 – 1.4.6  |                |\n|        0.7.0        |  1.5.0 – 1.5.1  |                |\n|        0.7.1        |      1.5.2      |                |\n|    0.7.2 – 0.7.4    |      1.6.0      |                |\n|    0.8.0 – 0.8.1    |  1.7.1 – 1.7.2  |                |\n|        0.8.2        |  1.8.0 – 1.9.0  |                |\n|        0.8.3        | 1.10.0 – 1.10.5 |                |\n|        0.9.0        |     1.11.0      |       19       |\n|        1.0.0        |  2.0.0 - 2.1.0  |       20       |\n|        1.1.1        |      2.2.*      |       21       |\n|        1.2.0        |      2.3.0      |                |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fy-lohse%2Finkjs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fy-lohse%2Finkjs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fy-lohse%2Finkjs/lists"}