パスの基点: 本文の相対パスは krkrz_dev リポジトリルート基準。作業ディレクトリが krkrz_dev 以外 (krkrz_android / krkrz_ios などの外枠や案件フォルダ) のときは ${KRKRZ_BASE}/krkrz_dev/ を前置して読む (echo $KRKRZ_BASE で実パスを確認。マシンごとに値が違うので絶対パスは書き込まない)。
吉里吉里Z 本体クラス API リファレンス
吉里吉里Z (kirikiri Z) が TJS2 から見えるクラス API のスキル。スクリプト
作者の視点で「どのクラスを使うか」「どのメソッドを呼ぶか」を素早く
引き当てるためのもの。深い説明は reference/*.md を Read で取りに行く。
重要: 作業に入る前に
- 下の「クロスカッティング概念」を必ず確認。Layer ツリー / イベント /
ストレージ / DrawDevice の思考モデルを取り違えると、API の組合せを
誤る ( 例: Layer は GUI 部品でもあり描画面でもある、Bitmap は Layer
とは別の独立した bits 領域 )。
- TJS2 言語そのものの疑問は別 skill (
tjs2) を参照。var / 辞書
リテラル %[ ... ] / new Foo() 括弧必須 など、JS と違う文法は
そちらに集約してある。
- クラス固有の詳細は
doc/reference/<Class>.md を Read。本ファイルは
入口で、深掘りは reference にある。
クロスカッティング概念 (これを取り違えると詰む)
Layer ツリー
- 1 ウィンドウは 1 つの プライマリレイヤ (Window.primaryLayer) を持つ
- Layer は親子のツリー構造。
parent/children/order で位置決め
- レイヤは「描画面 (画像を持つ Bitmap)」+「GUI 部品 (フォーカス・カーソル・hint・hitTest)」を 両方兼ねる
- 描画関連プロパティ:
width/height (描画領域), imageWidth/imageHeight (Bitmap 部分), clip* (クリップ矩形), face (描画面の種類), type (合成方式)
- Layer.face の値で
dfBoth/dfMain/dfProvince/dfAlpha 等を切替
- 入力:
cursor/hint/hitType/focusable/enabled がレイヤ単位、focused でフォーカス
- 描画:
loadImages/drawText/fillRect/copyRect/affineCopy 等。update() で再描画フラグ
- 動的生成は
new Layer(window, parent) + setImageSize(w, h) + setSize(w, h) がほぼ定型
イベント
- 同期イベント: メソッド呼び出し中に発生 ( 例: SoundBuffer の
onStatusChanged を play 中に )
- 非同期イベント: イベントキュー経由、他のハンドラ完了後に配信 ( 例:
onTimer、ユーザ入力 )
- 画面反映も非同期: 同じハンドラ内で何度
update しても、ハンドラから抜けるまで画面に出ない
- スクリプト側から非同期イベントを起こすには AsyncTrigger
- イベントハンドラの登録は プロパティに関数を代入 (
layer.onMouseDown = function(x, y, ...) { ... } )
- サブクラスから super のハンドラを上書きする場合は
function onTimer() { super.onTimer(...); ... } のような書き方
- 詳細:
doc/guide/EventSystem.md
統一ストレージ名 ( file://./... )
- 表記:
メディア://ドメイン/パス ( 区切りは / )
- ローカルファイル:
file://./c/program files/... ( Windows ドライブ文字含む )
- アーカイブ内:
archive.xp3>file.png (区切り >、2.19 beta 14 以降。旧 # は -arcdelim=# で互換可)
- 自動検索パス: Storages.addAutoPath で登録、相対名で findable に
- 全てのパスは
Storages.getFullPath で正規化される。TVP_NO_NORMALIZE_PATH 未定義ビルドではディレクトリ列挙結果も小文字化
- 詳細:
doc/guide/StorageSystem.md
ファイル/画像キャッシュ ( 2 層構造 )
DrawDevice ( ウィンドウ → 画面への描画器 )
- Window.drawDevice プロパティで切替可能
- 4 種: BasicDrawDevice (WINVER 既定、Direct3D), SDLDrawDevice (SDL3 既定、SDL_Renderer), OGLDrawDevice (OpenGL ES、Canvas/Shader/Texture/Offscreen が有効), NullDrawDevice (描画しない)。Canvas を SDL_GPU で動かすビルド (
KRKRZ_CANVAS_GPU、開発中) では GPUDrawDevice が既定で、OGLDrawDevice の名前でも使える (シェーダーは事前変換したパックから引く)
- OGLDrawDevice は lazy 初期化: TJS から差し替えた瞬間に GL コンテキスト生成、それまでは Canvas/Texture/Shader 等は使えない
- 起動時 default は
-drawdevice オプションで上書き可 ( sdl / sdlogl / ogl )
OpenGL 系 ( OGLDrawDevice 配下のみ有効 )
- Canvas — OGL 描画コンテキスト、
drawTexture/fillRect/drawTransition(表裏2テクスチャのクロスフェード/rule画像ユニバーサルトランジション内蔵、phase 0-1・rule は tcfAlpha・vague 0-255) 等
- Texture — GL テクスチャ。Bitmap や Storage から生成
- Offscreen — オフスクリーンレンダーターゲット
- ShaderProgram — GLSL シェーダ
- VertexBuffer / VertexBinder — 頂点バッファ
- OGLDrawDevice をアクティブにしていない状態でこれらを new しても無効
Bitmap と Layer の関係
- Bitmap は 独立した bits 領域。Layer.mainImageBuffer 経由でも触れるが、別オブジェクトとして new できる
- BitmapLayerTreeOwner は「Layer ツリーを Bitmap に書き出す」のためのコンテナ。スクリーンショットや動的レイヤレンダリングに使う
- Layer は描画面 + GUI、Bitmap は純粋なピクセル列。混同しない
finalize と invalidate
- すべてのクラスは GC または明示的
invalidate でオブジェクト破棄。finalize() メソッドが定義されていれば呼ばれる
- Window / Layer / Bitmap 等の重量級オブジェクトは明示的
invalidate を推奨
- finalize 内で例外を出すと処理系が苦しむので注意
クラス索引 ( doc/reference/<Name>.md を Read )
ファイルは krkrz_dev リポジトリルート相対で doc/reference/<Name>.md。
オンライン版は <https://wamsoft.github.io/krkrz_dev/reference/<name>/> 。
ウィンドウ / レイヤ / 描画
DrawDevice
OpenGL ( OGLDrawDevice 配下のみ )
サウンド / 動画
ストレージ / I/O
システム / イベント / プラグイン
プラグイン提供クラス (主要)
主要ユーティリティプラグイン (Scripts / Array / Dictionary 拡張)
これらは吉里吉里本体ではなくプラグインだが、実運用のスクリプトが常時前提にしていることが多い。standalone tool を書くときは自分でリンクが必要:
| プラグイン | 提供機能 | 備考 |
|---|
scriptsEx.dll | Scripts.foreach(obj, func, args*) / Scripts.getObjectKeys(obj) / Scripts.getObjectCount(obj) / Scripts.getObjectContext(obj) / Scripts.equalStruct(a, b) / Scripts.clone(obj) / Scripts.propSet / Scripts.propGet | Dictionary の列挙 API は本体に無いので事実上必須 |
saveStruct.dll | Array.save2(file, utf8=false, newline=0) / Array.saveStruct2(file, utf8, newline, opt) / Dictionary.saveStruct2(file, utf8, newline, opt) / .toStructString(newline, opt) | 組み込み Array.save は UTF-16 LE + BOM 固定なので、UTF-8 テキスト保存が必要ならこちらを使う |
fstat.dll | Storages.dirlistEx(dir) (size / attrib / 時刻付きの列挙) / ファイル属性の取得・設定 / 時刻の書き込み / fstat・getTime の atime・ctime | dirlist / dirtree / createDirectory / isExistentDirectory / fstat (size + mtime) / getTime (mtime) / currentPath (読取) は本体にもある (リンク不要、全ビルド可)。プラグインを読むと fstat / getTime / currentPath / dirlistEx はプラグイン版 (情報の多い版) に置き換わる。ディレクトリ引数は末尾 / 必須。SSOT = src/core/doc/LocalFileOps.md |
PackinOne.dll | 上記 fstat / saveStruct / scriptsEx の一部機能を統合提供 | wamsoft 独自の統合版。ただし link 時に fstat 経由でパス検証が走り、standalone 環境では init throw する場合がある。単機能を欲しいだけなら個別プラグインの方が安全 |
Scripts.foreach の落とし穴 ( scriptsEx.dll ):
コールバック関数の実行コンテキストは呼び出し元プラグイン側なので、外側関数の local 変数を参照するとランタイム例外になる。対策:
- 追加引数機構を使う:
Scripts.foreach(obj, function(k, v, arg) { ... }, arg)
Scripts.getObjectKeys(obj) で keys 配列を取り、素の for ループでイテレート (最も確実)
詳細は tjs2 skill の「クロージャの落とし穴」も参照。
共通パターン
イベントハンドラ登録
// プロパティに関数を代入
layer.onMouseDown = function(x, y, button, shift) { ... };
// または class サブクラスで override
class MyLayer extends Layer {
function MyLayer(win, parent) { super.Layer(win, parent); }
function onMouseDown(x, y, button, shift) {
super.onMouseDown(x, y, button, shift);
// 追加処理
}
}
Layer の典型初期化
var lay = new Layer(window, parent);
lay.setImageSize(640, 480); // Bitmap 部分のサイズ
lay.setSize(640, 480); // 表示サイズ
lay.setPos(0, 0); // 位置
lay.loadImages("bg/title"); // 自動検索パスから
lay.visible = true;
非同期画像読み込み + cache
Storages.addCacheTargetExtension(".png");
Storages.addDecodeTargetExtension(".png");
Storages.requestCache("bg/title.png"); // 非同期 prefetch
// ... 後で loadImages したときに cache hit
Timer 周期処理
class MyTimer extends Timer {
function MyTimer() { super.Timer(); interval = 1000; enabled = true; }
function onTimer() { /* 1秒毎 */ }
}
DrawDevice 切替で OGL 有効化
// OGLDrawDevice に切替えてから Canvas/Shader 系を new する
window.drawDevice = new OGLDrawDevice();
var canvas = new Canvas(window);
var tex = new Texture(window, "image.png");
関連ドキュメント
- ガイド (概念解説):
doc/guide/EventSystem.md, doc/guide/StorageSystem.md, doc/guide/GraphicSystem.md, doc/guide/SoundSystem.md, doc/guide/CommandLine.md
- 読み上げ (スクリーンリーダー):
doc/guide/Accessibility.md。Layer に描いた UI は ElementsDialog.setGameA11y (ノード表を渡す) か ElementsDialog.a11yLayers = true (フォーカス連鎖の Layer を自動で載せる。Layer に a11yName / a11yRole / a11yHidden / onA11yAction などを生やして補う — 一覧は doc/reference/Layer.md のクラス説明)。任意の文は ElementsDialog.announce
- 周辺情報:
doc/topics/core/*.md (gamepad〔刻印/位置 2 系統・padStyle〕, viewport, engine_setting, memory_observation, low_memory, draw_stats, pad_overlay, repl, logging, anti_cracking)
- TJS2 言語本体は別 skill (
tjs2)
関連スキル
- skill
tjs2 — TJS2 言語仕様と組込クラス (Array / Dictionary / Math / Date / RegExp / Exception 等)
- (未作成) 吉里吉里Z 内部構造 / engine internals — C++ 実装、レンダリングパイプライン、SIMD、プラグインローダ等
エンジン内部は別 skill 化予定。本スキルは TJS から見える表層 API のみ。