hsp3dx 仕様書 Phase 0 ドラフト

最終更新: 2026-04-20

hsp3dx は HSP3 言語を DxLib ベースのランタイムで動かすクロスプラットフォーム実行環境。 Windows / iOS / Android の 3 プラットフォームで 同一の .ax バイト列 を実行できることを目指す。

1. 設計コンセプト

HSP3Dish との差別化ポイント (4 点)

1. 真の "同一 .ax が 3 プラットフォームで同じ VM で走る"
   HSP3Dish mobile は hsp3cnv で .ax → C++ AOT 翻訳して native ビルドするため、Win (interpret) と mobile (AOT native) で実行コードパスが違う。hsp3dx は全プラットフォームで VM インタプリタ統一のため、挙動再現性が高い (Win で出たバグは mobile でも同じ VM で再現)。
2. DxLib の豊富な API をそのまま呼べる (3D / エフェクト / 動画再生 / ネットワークなど 2000 関数超、HSP3Dish は 2D + 簡易 3D のみ)
3. DxLib 既存ユーザーの資産移行パス
4. 新命令追加時に翻訳ルール不要 (hsp3cnv に HSP→C++ 翻訳ルール追加が要らない、プラグイン側の命令表だけでよい)

Route B を採用した理由 (Route A との比較)

ランタイム構成と hgio 差し替え戦略

hgio = HSP Graphics I/O。HSP3Dish が導入した描画/音声/入力の抽象層で、VM からは統一 C++ 関数群 (hgio_init / hgio_render_start / hgio_gsel など) だけが見える。プラットフォーム別実装を差し替えることでマルチプラットフォーム化する設計。

hsp3dx では hgio_dx.cpp を新規に書いて hgio_init → DxLib_Init、hgio_render_start → ClearDrawScreen、のように DxLib API に転送する。VM 側 (hsp3embed) は一切触らない。

さらに DxLib の 2000 関数を dx_* 命令として HSP 側に公開する dxlib_core プラグイン を別途静的リンクする。これにより (a) 既存 HSP コード (mes など) の互換性 と (b) DxLib 全 API フルアクセス の両立。

2. HSP コマンド分類

2.1 採用する (pure HSP / 言語コア)

2.2 除外する (Win32 依存で iOS/Android に持っていけない)

2.3 DxLib 経由で置換提供する命令

詳細は Phase 1 以降で 40 関数から順次拡張。分類は以下:

3. 型システムの進化計画

DxLib は float / 構造体 / 構造体配列 を多用するため、段階的に HSP の型システムを拡張する必要がある。本章で 段階的移植計画 を明記する。

3.1 DxLib が使う型 / 機構

3.2 hsp3net にあって hsp3embed に無い型機構

ベースとする hsp3embed は HSP3 素の型セット (int / double / str / 配列) しか持たない。対して hsp3net には以下が実装済:

3.3 取れる 3 方針

3.4 Phase と方針の対応

3.5 長期ベース判断 (Phase 1.1 で前倒し確定 / Phase 6 で再々考)

3.6 自動コード生成の指針

DxLib の 2000 関数を手書きで #deffunc / #cfunc 定義するのは非現実的 → DxLib.h をパースして機械生成するスクリプトを Phase 5 で整備予定。

• Phase 5 自動生成: 方針 2 ベース (float 対応済、構造体はスカラ分解)
• Phase 6 自動生成: 方針 3 ベース (NSTRUCT 対応済、構造体そのまま渡せる)
• 方針 1 期のプラグイン手書きコードは Phase 5 で 生成コードに置き換わって捨てる前提 で書く (繋ぎコードに投資しすぎない)

3.7 コールバック方針 (iOS / Android 制約への対処)

DxLib には SetMovieSurfaceCallback / サウンドストリーム / ネットワーク受信 / MV1 当たり判定など C 関数ポインタを受ける API が 10〜20 個存在する。これを HSP 側から扱う方針。

3.7.1 プラットフォーム制約

3.7.2 コールバック 3 技法と対応

3.7.3 静的スロット方式の具体像

// ビルド時に signature family ごとに N 個事前生成 (DxLib.h パース時に自動)
static int g_hsp_label[256];
static void cb_slot_0(int arg0, int arg1) {
    VM_CallHspLabel(g_hsp_label[0], arg0, arg1);
}
static void cb_slot_1(int arg0, int arg1) { ... }
/* ... cb_slot_255 まで ... */

static void (*trampolines[256])(int,int) = {
    cb_slot_0, cb_slot_1, /* ... */, cb_slot_255
};

HSP 側:

dx_set_callback_xxx *my_handler     ; プラグインが空きスロットを確保、ラベル ID を記録
...
*my_handler
    ; DxLib からコールバックされたときここに来る
    return

3.7.4 制約と運用

• シグネチャごとに別スロット群が必要 (void(int,int) と void(float*) はスロット共有不可) → DxLib のコールバック API は 10〜20 種、5〜10 種類のシグネチャで各 256 スロット事前生成で実用十分
• 同時登録可能数に上限あり (スロット数まで) → ゲーム用途では問題にならない
• スレッド安全性: DxLib 側が別スレッドから呼ぶ API では VM ロック必須 (VM を呼ぶ前に mutex 取得)

3.7.5 Phase 対応

3.7.6 §3.2 の #defcbcom 記述の補足

4. プラグイン方針

同梱プラグインは 事前承認制 (ランタイムビルド時に静的リンク) となる。

4.1 OK プラグイン pure HSP / cross-platform 可

4.2 NG プラグイン 使えない

5. 文字コード規則

5.1 統一ルール

5.2 DxLib 公式ドキュメント準拠

• Windows DxLib: デフォルトは Shift-JIS / UTF-16LE、SetUseCharCodeFormat で切り替え可
• Android / iOS DxLib: UTF-8 固定
• hsp3dx ランタイムは 起動時必ず SetUseCharCodeFormat(DX_CHARCODEFORMAT_UTF8) を呼ぶ → 3 プラットフォームで統一

5.3 移行時の既知の落とし穴

5.4 既存資産の移行サポート

tools/hsp3dx_sjis2utf8/ に .hsp ソースを Shift-JIS → UTF-8 に一括変換するツールを同梱。

hsp3dx_sjis2utf8 --in path\to\src.hsp [--out path\to\dst.hsp]
hsp3dx_sjis2utf8 --dir path\to\project [--recursive]
hsp3dx_sjis2utf8 --dir path\to\project --dry-run

6. ビルド / 配布フロー

6.1 Windows

6.2 iOS

起動時にランタイムが [NSBundle pathForResource:@"start"] 経由で start.ax のパスを得て、通常の fopen で読み込んで VM にロード → interpret 実行。画像や音声と同じ扱いで bundle resource としてアクセスするシンプル構成。

6.3 Android

ランタイムは AAssetManager_open() 経由で start.ax を読み込み、通常通り VM interpret。画像/音声も同じ AAssetManager 経由。

6.4 配布経路が統一されている点

6.4 共通アセットパッケージング

.ax 以外の素材 (画像 / 音声 / フォント) は hsp3dx_pack ツール (Phase 2) で仮想 FS に固める。ランタイムはプラットフォーム問わず同じ API で素材にアクセス可能。

7. Phase 計画

7.1 Phase 2 (旧) 見送りの経緯

8. ディレクトリ構成 (Phase 0 時点)

hsp3dx/
  README.md                    このドキュメントへのリンク
  samples/
    sample_drawgraph.hsp       Phase 1 検証用サンプル (雛形)
    sample_sound.hsp           Phase 1 検証用サンプル (雛形)
    sample_mouse.hsp           Phase 1 検証用サンプル (雛形)
  win32/                       Phase 1 で hsp3dx.exe のソース/vcxproj を配置
    README.md
  ios/                         Phase 3 で Xcode プロジェクトを配置
    README.md
  ndk/                         Phase 4 で Android Studio プロジェクトを配置
    README.md

docs/
  hsp3dx_spec.md               Markdown 版仕様書
  hsp3dx_spec.html             本ドキュメント

tools/
  hsp3dx_sjis2utf8/            SJIS → UTF-8 一括変換ツール (.NET)
    hsp3dx_sjis2utf8.csproj
    Program.cs
    README.md

9. 未確定事項 (Phase 1 着手時に決める)

• VM ソースは hsp3net を fork するか hsp3dish を fork するか → Phase 0 時点では hsp3embed fork で合意
• hsp3embed を fork → Phase 1.1 で訂正: hsp3/ コア (Hsp3 クラス) を fork で確定
  理由: hsp3embed の Hsp3r::Reset() は __HspInit(Hsp3r*) (hsp3cnv が .ax ごとに自動生成) に依存しており、Route B (runtime .ax interpret) 方式と非互換。 hsp3/ の Hsp3::Reset(int mode) は runtime に .ax を読み込んで HSPHED 解析まで自己完結する。参考実装は hsp3/win32/hsp3cl.cpp
• DxLib SDK の取得方法 → 公式配布 zip を各自 DL (リポジトリ非含有、.gitignore 管理)
• DxLib ライセンス条項確認 → 商用 OK / ライセンス料なし / 再配布時は著作権表記必須
• プラグイン ID テーブルの設計 (HSP 命令 ID 付与ルール)
• sdim のバイト数自動調整をランタイム側で行うか (互換性のため)
• hsp3dx 独自の拡張命令 (dx_* prefix) を iron_dxlib.hsp に畳み込むか、ランタイム組み込みにするか

Markdown 版: hsp3dx_spec.md ／ リポジトリ: hsp3dx/