Valueツール | Gua 日本語リファレンス

例: 所持アイテムが揃っているか確かめる

ゲームから届いた「keyとmapを持っている」というJSONを、期待した集合と比べます。JSON文字列をparseValueへ渡すと検証済みの値が得られ、valuesEqualは同じ内容かをbooleanで返します。形式が不正ならValueErrorが発生します。

順番が異なる集合を比較ts

import { parseValue, valuesEqual } from "gua-value-tools";

const actual = parseValue('{"type":"set","elementType":"string","value":["key","map"]}');
const expected = parseValue('{"type":"set","elementType":"string","value":["map","key"]}');
console.log(valuesEqual(actual, expected)); // true

ゲーム側では、画面に直接出ていない値をObserveとして登録します。これは「追加の観測値を公開する」機能です。gua-value-toolsは受け取った値を扱い、ゲームへの登録や接続は行いません。Observeの登録・npmパッケージの組み合わせ

パッケージを導入する

パッケージを導入powershell

npm install gua-value-tools@latest

新規導入向けの指定です。既存のゲームに合わせる版の選び方とlockfileはnpmパッケージガイドを参照してください。

gua-value-toolsはTypeScriptの型と検証、JSON入出力、enum catalog、意味的な等価比較を提供します。

enumは、決められた候補から選ぶ値です。例えばボスの段階がFirstかSecondのどちらかなら、その候補をEnumCatalogへ登録します。未知の候補や別の型は検証で拒否されます。

enumの読取・検証・比較ts

import { EnumCatalog, parseValue, serializeValue, valuesEqual } from "gua-value-tools";

const catalog = new EnumCatalog();
catalog.register("game.BossPhase", ["First", "Second"]);
const value = parseValue(
  '{"type":"enum","enumType":"game.BossPhase","value":"Second"}', catalog);
console.log(serializeValue(value, catalog));
console.log(valuesEqual(value, value, catalog));

型と等価比較

型	契約
`bool`、`string`	真偽値と有効なUnicode scalar文字列。大小文字変換・Unicode正規化を行いません。
`integer`	−9007199254740991から9007199254740991の数学的整数。binary64へ丸める前に検証します。
`number`	有限binary64。同じ数値でもintegerとは別型です。
`enum`	明示登録したenumTypeと候補名。異なるalias名は非等価です。
`list`	順序付きの同種scalar要素。重複を許可します。
`set`	同種scalar要素。比較では順序を無視し、重複を拒否します。JSON出力は入力順を保持します。

空のlistやsetもelementTypeと必要なenumTypeを保持します。null、任意のオブジェクト、オブジェクト参照、入れ子のlistやset、BigInt、NaN、Infinityは禁止です。型が異なる有効値は非等価、不正値は検証エラーです。JSONのバイト一致ではなくvaluesEqualを使ってください。

enum候補の登録と変更

game.BossPhaseのようなドットで区切った明示的なIDと、重複のない空でない候補集合を登録します。同じIDと同じ候補集合の再登録は順序にかかわらず成功し、異なる集合は拒否します。定義変更には新しいIDを使います。空のenumのlistやsetを含め、検証・出力・比較には対応する候補一覧を渡してください。候補一覧は自動で共有されず、言語の型名からIDを推定しません。

C++・C#で同じ値を扱う

同じ契約をgua/value.h、C++のgua::Value/gua::EnumCatalog、Gua.Core.GuaValue/GuaEnumCatalogで使えます。C++と.NETは共通のネイティブAPIを呼び出します。TypeScript packageも同じ型付きValueの意味を提供します。

1.1.0に固定した参照: package API、Valueの意味・ABI契約、schema。