ink language integration

Pixi’VN は、分岐型ストーリー向けに設計されたスクリプト言語 ink を使用して、インタラクティブな物語を作成できます。

「ink」とは？ ink はインタラクティブストーリーのためのシンプルなスクリプト言語であり、 80 Days、Heaven’s Vault、Sorcery! などのゲームで使用されています。 詳しくは ink 公式サイト を参照してください。

ink と Pixi’VN の統合 は、inkjs と PixiVNJson を使用して ink コード を解析し、Pixi’VN が解釈できる JSON を生成します。 これにより、JavaScript/TypeScript と ink は同じストレージとキャンバスを共有し、JavaScript/TypeScript から ink の knot（または label）を起動したり、その逆を行うことができます。 つまり、ink で物語を書き、JavaScript/TypeScript でミニゲームや高度なアニメーションを制御することができます。

=== start ===
We arrived into London at 9.45pm exactly.

* "There is not a moment to lose!"[] I declared.
 -> hurry_outside

* "Monsieur, let us savour this moment!"[] I declared.
 My master clouted me firmly around the head and dragged me out of the door.
 -> dragged_outside

* [We hurried home] -> hurry_outside

=== hurry_outside ===
We hurried home to Savile Row -> as_fast_as_we_could

=== dragged_outside ===
He insisted that we hurried home to Savile Row
-> as_fast_as_we_could

=== as_fast_as_we_could ===
<> as fast as we could.
-> start

なぜこれを使うのか？

JavaScript/TypeScript で直接ナラティブを書くのは、初心者にとって特に時間がかかり、複雑です。 ink は学習も記述も非常に簡単です。

新しい開発者は、ink テンプレート から始め、徐々に JavaScript/TypeScript の高度な機能を学ぶことができます。

インストール

既存の JavaScript プロジェクトに ink パッケージを追加するには、次のいずれかのコマンドを実行します：

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

初期化

インストール後、importInkText() を使用して ink スクリプト を読み込みます：

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

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

importInkText([inkText, ...])

次に、Pixi’VN 関数 を使用して ink の knot（または label）を実行できます：

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

narration.call(`start`, {})

今後の機能

以下の機能は現在開発中です。

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

Pixi’VN によって無視される ink 構文

一部の ink 構文は Pixi’VN では無視されます。 これらは Inky エディターでのテストなどに使用できますが、Pixi’VN はそれらを処理しません。

INCLUDE

INCLUDE is an ink statement to include another ink file. In Pixi’VN, you should use importInkText() to load multiple ink files instead, so INCLUDE is ignored.

Narration outside the knots

Narration outside the knots (or labels) is ignored, except for variables.

For example:

VAR my_var = false // ✅ This will be handled (because it is a variable)
Hello // ❌ This will be ignored  [!code warning]
-> start // ❌ This will be ignored [!code warning]
=== 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 two 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 two different dialogues, but the following dialogue: 2 of Diamonds.\n\n'You lose this time!' crowed the croupier.. In Markdown it will be displayed like this:

  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