Ink Language Integration

pixi-vn-cover-ink

Pixi’VN gives you the ability to write your own narrative using Ink.

What is ink?

Ink is a scripting language for writing interactive narrative. It is used in games like 80 Days, Heaven's Vault, and Sorcery! to create branching stories.

This language is very simple to learn. Go on ink website to learn more about it.

Why use Ink integration?

Programming a game narrative in Javascript/Typescript has the advantage of having total development freedom, but the disadvantage is that it slows down the writing of a narrative (it makes you write a lot of code).

Javascript/Typescript and Ink share the same memory and canvas, and it is also possible to launch Ink labels (or knots) from Javascript/Typescript and vice versa. This allows you to use the best of both languages. You can use Ink to write the narration, while using Javascript/Typescript to create minigames or complex animations.

The novice developers can use a ink template to start developing just with Ink, and then gradually learn Javascript/Typescript to create more complex features.

Start using Ink in Pixi’VN

If you have not created a project yet then it is recommended to use the template to start your project with Ink.

Otherwise to add ink to your Pixi’VN project you need to install the @drincs/pixi-vn-ink package.

# npm
npm install @drincs/pixi-vn-ink

# yarn
yarn add @drincs/pixi-vn-ink

# pnpm
pnpm add @drincs/pixi-vn-ink

# bun
bun add @drincs/pixi-vn-ink

After installing the package you need to use the importInkText() function to import the ink script into your project.

// main.ts
import { importInkText } from '@drincs/pixi-vn-ink'

const inkText = `
=== start ===
Hello
-> END
`

importInkText([inkText, ...])

Now you can run the ink knot (or label) with Pixi’VN functions.

import { narration } from '@drincs/pixi-vn'

narration.callLabel(`start`, {})

Import text contained in .ink files

For this guide we will use the Vite project, but you can use the same logic in other projects.

To import text contained in .ink files you need create the file ink.d.ts:

// src/ink.d.ts
declare module '*.ink' {
    const value: string
    export default value
}

After that you need to add the .ink extension to the assetsInclude option in the vite.config.ts file:

// vite.config.ts
export default defineConfig({
  // ...
  assetsInclude: ['**/*.ink'],
})

After that you can import the ink file and add ?raw at the end of the import to get the text content.

// main.ts
import { importInkText } from '@drincs/pixi-vn-ink'
import startLabel from './ink_labels/start.ink?raw'

importInkText([startLabel, ...])

Ink features in development

The following features are in development and will be added in the future:

( Add a like or comment to the issue to show your interest )

Functions and Game Queries (issue #11):
- User-created functions (issue #32)
- CHOICE_COUNT()
- TURNS()
- TURNS_SINCE()
- SEED_RANDOM()
LIST (issue #15)
Tunnels (issue #38)
Threads (issue #39)

Ink syntax that will be ignored by Pixi’VN

The following syntax will be ignored by Pixi’VN. You can use them in your ink script ( For example if you want test your script with Inky editor ), but they will be ignored by Pixi’VN.

INCLUDE

INCLUDE is used by Ink to import other ink files.

In Pixi’VN you can use the importInkText() function to import the ink files. So if you use INCLUDE it will not be handled, so it does not import the files.

Narration outside the knots

The narration outside the knots (or labels) will be ignored, except for variables. The reason is that you must run the first knot (or label) with the Pixi’VN functions.

So for example the following cases will be ignored:

VAR my_var = false ✅ This will be handled (because it is a variable)
Hello # ❌ This will be ignored
-> start # ❌ This will be ignored
=== start === # ✅ This will be handled
My name is John # ✅ This will be handled
-> DONE # ✅ This will be handled

Differences between Native Ink and Pixi’VN Ink

in this case:
```
{ shuffle:
  -  2 of Diamonds.
    'You lose this time!' crowed the croupier.
}
```
In Native Ink, you will see 2 different dialogues, the first one will be 2 of Diamonds. and the second one will be 'You lose this time!' crowed the croupier..

In Pixi’VN Ink, you will not see 2 different dialogues, but the following dialogue: 2 of Diamonds.\n\n'You lose this time!' crowed the croupier.. In Markdown it will be displayed as:
```
2 of Diamonds.
'You lose this time!' crowed the croupier.
```
if a weave (In following example shove) is attached to a one time choice, and it is opened with -> shove it will not invalidate the one time choice. To invalidate it you will have to select the choice as usual.

Here is an example:
```
-> start
=== start ===
* [1] -> shove
* (shove) [2] 2
* {shove} [3] -> END
-  -> start
-> DONE
```
In case you take choice 1, the second time it will be opened start:
- if you use Native Ink, you will only be able to choose choice 3. The choice 2 is hidden because being "one time" Native Ink will know that you have already made this decision with -> shove.
- if you use Pixi’VN Ink, you will be able to choose choice 2 or 3. The choice 2 is not hidden because Pixi'VN Ink doesn't know that shove is paired with a choice.
To get the same logic as start both in Native Ink and Pixi'VN Ink you will have to write the following code:
```
-> start
=== start ===
* [1] -> shove
* (shove) {!shove} [2] 2
* {shove} [3] -> END
-  -> start
-> DONE
```

DRincs-Productions / pixi-vn-ink

readme