hsp3dx 利用者ガイド

hsp3dx は HSP3 + DxLib を同じ .ax バイナリで Windows / Android / iOS (iOS は未着手) で動かすランタイムです。 HSP3Dish と違い、DxLib の 2000 関数超の API をモバイルでもそのまま呼べることを目指しています。

本ドキュメントは 2026-04-22 時点 (Phase 5.5n + Phase 3 iOS + Phase 4 Android + Phase M.1〜M.6 完了) が対象です。

1. hsp3dx とは

特徴

• HSP 組み込み命令 (color / boxf / mes / gcopy / mmload 等) が素のまま使える
• DxLib API を dx_* プレフィックス付きで 1723 関数 直接呼べる (自動生成)
• #defstruct (NSTRUCT) で VECTOR / MATRIX / VERTEX3D 等の DxLib 構造体を扱える
• UTF-8 固定 (3 プラットフォーム共通のため)
• HTTP / JSON / WebSocket は hsp3dx 独自命令として組み込み (dx_http_* / dx_json_* / dx_ws_*)

カバレッジ数字 (2026-04-21)

2. 導入とビルド

前提

• Windows 10/11 (x64)
• Visual Studio 2022 Community + "C++ によるデスクトップ開発" ワークロード
• DxLib SDK (Ver 3.24f 以降) が hsp3dx/extlib/dxlib_win/DxLib_VC/ に配置済

ランタイムのビルド

1. hsp3dx/win32/hsp3dx.vcxproj を MSBuild で Release/x64 でビルド
2. hsp3dx/win32/bin/Release/hsp3dx.exe が生成される

msbuild hsp3dx\win32\hsp3dx.vcxproj -p:Configuration=Release -p:Platform=x64

スクリプトのコンパイルと実行

rem 1. UTF-8 ソースを .ax にコンパイル (-i は入力 UTF-8、-d はデバッグ情報)
package\win32\hspcmp64.exe -i -d your_script.hsp

rem 2. 実行
hsp3dx\win32\bin\Release\hsp3dx.exe your_script.ax

3. Hello, hsp3dx

#bootopt hsp64 1
#cmpopt utf8 1
#include "iron_dxlib.as"

    color 20, 30, 60
    boxf 0, 0, 640, 480
    color 255, 220, 80
    font "MS Gothic", 20
    pos 100, 200
    mes "Hello, hsp3dx!"
    redraw 1

    repeat
        await 16
        getkey k, 27
        if k : break
    loop
    end

これだけで HSP 組み込み命令が DxLib の back buffer 経由で描画されます。 ESC で終了します。

4. 4 つの API 系統

(a) HSP 組み込み命令

color / boxf / circle / line / mes / gcopy / celload / picload / mmload / mmplay / buffer / screen / redraw / await 等 ― 標準 HSP 資産がそのまま使えます。

(b) 手書き dx_* 命令 (73 個、文形式)

ユースケース特化のラッパ。スカラー引数でシンプルに呼び出せる簡易版や、 hsp3dx 独自の HTTP / JSON / WebSocket / コールバック登録が含まれます。

命名は snake_case が中心 (例: dx_setcamerapos, dx_http_get)。

(c) 自動生成 dx_* 命令 (1650 個、文形式)

DxLib.h を正規表現で parse し、HSP から直接呼べる形に機械変換したもの。 命名は DxLib 原関数名そのまま + dx_ プレフィックス (例: dx_DrawSphere3D, dx_VectorAdd)。 DxLib 公式リファレンスの関数名がそのまま検索語として使えます。

(d) 自動生成 dx_*_f 命令 (1144 個、式形式)

スカラー戻り値のものは Phase 5.5p で #ccmd 対応 = 式として呼べる 版も提供:

; (c) 文形式: stat 経由 or 第 1 引数で受け取る
dx_GetColor col, 255, 0, 0    ; col = stat 相当

; (d) 式形式: 自然な代入式で書ける
col = dx_GetColor_f(255, 0, 0)

命名は (c) 版に _f (function form) を付けた形。対象は純粋なスカラー戻り + スカラー入力のみ (ref 引数 / struct 引数 / struct 戻り値の関数は文形式のみ)。

手書き版と直接版の使い分け

スカラー引数で呼びたい場合は _s サフィックスの手書き版 (dx_drawsphere3d_s、xyz 直書き)、 VECTOR 引数を使いたい場合は auto-gen 版 (dx_DrawSphere3D) を選んでください。

5. #defstruct で DxLib 構造体を扱う

VECTOR / MATRIX / COLOR_F / VERTEX3D 等の DxLib 構造体は、HSP 側で #defstruct 宣言 → stdim で確保 → -> 演算子でメンバアクセスします。 HSP 3.7 の NSTRUCT 型 (FLAG=11) を使ったバイナリレイアウト保持です。

基本: VECTOR

#defstruct VECTOR
    #field float x
    #field float y
    #field float z
#endstruct

stdim v, VECTOR
v->x = 10.0
v->y = -5.0
v->z = 100.0

mes "v = (" + v->x + ", " + v->y + ", " + v->z + ")"

配列

stdim pts, VECTOR, 10       ; VECTOR 10 個分
pts(0)->x = 1.0
pts(1)->y = 2.0

ネスト構造体

#defstruct POINT
    #field int x
    #field int y
#endstruct

#defstruct RECT
    #field POINT topLeft
    #field POINT bottomRight
#endstruct

stdim r, RECT
r->topLeft->x = 10
r->bottomRight->y = 200

文字列フィールド

#defstruct PERSON
    #field int  age
    #field char name[32]      ; 配列長は [N] 記法 (空白区切りは不可)
    #field float height
#endstruct

stdim alice, PERSON
alice->age = 30
alice->name = "Alice Smith"
alice->height = 162.5

union

#defunion FLOAT_INT
    #field float f
    #field int   i
#endunion

stdim u, FLOAT_INT
u->f = 1.0
mes "IEEE 754 bit pattern: " + u->i    ; → 1065353216 (= 0x3F800000)

6. 3D 描画

基本セットアップ

dx_setzbuffer 1                ; Z バッファ ON (深度テスト)
dx_SetUseLighting 1            ; 照明 ON
dx_setlightdir 0.3, -0.5, 0.8  ; 平行光源の方向
dx_setcameraperspective 60     ; 視野角 60 度
dx_setcamerapos 400, 150, -400, 0, 0, 0   ; 視点, 注視点

スカラー版 (_s) とスカラー版 (auto-gen VECTOR 版)

球を描くのに 2 通りあります:

; 手書き scalar 版 (簡潔)
dx_drawsphere3d_s 0, 0, 0, 80, 16, 0xFF4040, 0, 1

; auto-gen VECTOR 版 (DxLib 原シグネチャ)
stdim v, VECTOR
v->x = 0.0 : v->y = 0.0 : v->z = 0.0
dx_DrawSphere3D v, 80.0, 16, 0xFF4040, 0, 1

主要な 3D プリミティブ

MV1 3D モデル

dx_mv1load "model.mv1"
h = stat
dx_mv1setpos    h, 0, 0, 0
dx_mv1setrot    h, 0, 0.5, 0    ; ラジアン
dx_mv1setscale_s h, 1.0, 1.0, 1.0

; 描画ループ内
dx_mv1draw h

7. HTTP / JSON / WebSocket

HTTP GET / POST

dx_http_set_timeout 10000
dx_http_set_user_agent "MyApp/1.0"

dx_http_get "https://httpbin.org/get?foo=bar", resp
status = stat                   ; HTTP ステータスコード
mes "body size = " + strlen(resp)

dx_http_post "https://api.example.com/echo", "{\"x\":1}", resp2, "application/json"

拡張機能: PUT / DELETE / PATCH / download / multipart upload / Basic 認証 / Cookie 保持 / レスポンスヘッダ取得 がすべて揃っています。 Windows 版は WinHTTP ベース、HTTP/2 と gzip/deflate 自動解凍対応。

JSON

; パース
dx_json_parse "{\"name\":\"hsp3dx\",\"ver\":5.5,\"tags\":[\"win\",\"ios\"]}"
h = stat
dx_json_get_str  h, "name", s_name         ; "hsp3dx"
dx_json_get_int  h, "ver"                   ; stat = 5 (整数化)
dx_json_size     h, "tags"                  ; stat = 3

; 構築
dx_json_new_obj
h2 = stat
dx_json_set_str    h2, "app", "MyGame"
dx_json_set_arr    h2, "players"
dx_json_set_str    h2, "players[0]", "Alice"
dx_json_stringify  h2, out

dx_json_free h
dx_json_free h2

path は "user.items[0].name" 記法 (picojson ベース)。

WebSocket

dx_ws_connect "wss://ws.ifelse.io/"
h = stat
if h < 0 : dialog "接続失敗" : end

dx_ws_send_text h, "{\"hello\":\"world\"}"
dx_ws_recv h, buf, 3000          ; timeout 3 秒
recv_type = stat                 ; 0=TEXT / 1=BINARY / -1=closed / -2=timeout

dx_ws_close h
dx_ws_free  h

8. コールバック登録

DxLib のコールバック取る API (全 5 種) を HSP ラベルで受けられます。 内部は C スタブから code_callback() 経由で HSP VM にジャンプする「静的スロット方式」。

対応命令

例: 非同期画像ロード完了時のコールバック

dx_SetUseASyncLoadFlag 1
dx_LoadGraph "big_texture.png"
h_pic = stat

dx_SetASyncLoadFinishCallback h_pic, *on_loaded

; 以降の処理はロードと並列で進む
repeat
    await 16
    ; ...
loop

*on_loaded
    ; ロード完了したらここが呼ばれる
    mes "loaded!"
    return

9. 頂点配列描画 (DrawPolygon3D)

任意メッシュを描きたい場合、VERTEX3D 配列を直接 DxLib に渡せます。

#defstruct VERTEX3D
    #field float px
    #field float py
    #field float pz
    #field float nx
    #field float ny
    #field float nz
    #field byte  dr    ; diffuse R
    #field byte  dg
    #field byte  db
    #field byte  da
    #field byte  sr    ; specular R
    #field byte  sg
    #field byte  sb
    #field byte  sa
    #field float u
    #field float v
    #field float su
    #field float sv
#endstruct

stdim verts, VERTEX3D, 3
verts(0)->px = -100.0 : verts(0)->py =   0.0 : verts(0)->pz = 0.0
verts(0)->dr = 255    : verts(0)->dg = 80    : verts(0)->db = 80    : verts(0)->da = 255
; ... 残りの頂点も同様

dx_DrawPolygon3D verts, 1, -1, 1   ; ポリゴン数 1、テクスチャなし、半透明考慮

インデックス付き (DrawPolygonIndexed3D) / 32bit インデックス / 2D 版も同じパターンで使えます。

10. よくあるハマりどころ

⚠ 変数名と HSP 組み込み命令の衝突

stdim pos, VECTOR のように pos / line / color / font / rank / default など HSP 予約名を変数名にすると syntax error。 v や pt などの短い名前や固有の名前を使ってください。

⚠ #field 配列の書き方

空白区切りは NG、[N] 記法必須:

#field char name 32       ; ❌ array_count = 0 になる
#field char name[32]      ; ✅

⚠ 座標スケール

DxLib のデフォルト near plane は 1.0。3D 座標が -5〜5 等だと near plane に近すぎて見えない場合あり。 既存 sample_3d は ±100〜350 スケールで書かれています。

⚠ grHandle = -1 は DX_NONE_GRAPH とは違う

DxLib の「テクスチャなし」は 0xfffffffb (DX_NONE_GRAPH) だが、HSP からは -1 で渡せるように runtime 側で自動変換しています (Phase 5.5n)。

⚠ 非 int 戻り値の DxLib 関数は第 1 引数で受ける

HSP の #cmd は文専用で式返却不可。そのため float / double / VECTOR / MATRIX 等の戻り値は 第 1 引数の変数に書き戻されます:

dx_GetNowHiPerformanceCount t          ; LONGLONG 戻り → t に代入
dx_ConvWorldPosToScreenPos out, world  ; VECTOR 戻り → out に代入

11. Android 版の使い方

Phase 4 完了 (2026-04-21) により、Win 版と同じ .ax バイナリを Android 端末で実行できます。NativeActivity ベースの APK として ビルドし、エミュレータ / 実機の両方で動作確認済みです。

基本フロー

1. Windows で .hsp を hspcmp64.exe -i -u --compath=..\package\win32\common\ your_game.hsp でコンパイル
2. 出力された your_game.ax を hsp3dx/ndk/template/app/src/main/assets/start.ax にリネームコピー
3. cd hsp3dx/ndk/template && gradlew.bat assembleDebug で APK ビルド
4. adb install -r app/build/outputs/apk/debug/app-debug.apk でインストール

詳細は hsp3dx/ndk/README.md を参照。

Android 固有機能

画面サイズと座標系

論理解像度は screen 0, w, h で任意に変更可能 (初期値 640×480)。 物理画面にはアスペクト比維持 letterbox (上下または左右に黒帯) で表示され、 mousex / mousey 等のタッチ座標も論理座標系で返ります。

; 縦長スマホ向け
screen 0, 720, 1280

; 端末ネイティブ解像度で 1:1 描画
dx_getdispsize dw, dh
screen 0, dw, dh

; ショートカット (同上)
screen 0, 0, 0

; 比率無視でストレッチ (画面いっぱい)
dx_setscreenfit 1

マルチタッチの例 (2 本指の距離)

dx_getmtouchnum
n = stat
if n >= 2 {
    dx_getmtouch 0, x0, y0
    dx_getmtouch 1, x1, y1
    dist = sqrt((x1-x0)*(x1-x0) + (y1-y0)*(y1-y0))
    ; dist がピンチ量の基礎
}

multipart/form-data アップロードの例

dx_http_mp_begin
dx_http_mp_add_text "description", "photo of my dog"
dx_http_mp_add_file "photo", "dog.jpg", "image/jpeg", ""
dx_http_mp_post "https://api.example.com/upload", resp
status = stat                ; HTTP status
dx_http_mp_end

開発中のサンプル差し替え (APK リビルド不要)

開発中は adb push で .ax を差し替え可能:

adb push sample_foo.ax /data/local/tmp/ax_override.bin
adb shell "run-as com.ironhsp.hsp3dx sh -c \
    'cp /data/local/tmp/ax_override.bin /data/data/com.ironhsp.hsp3dx/files/start_override.ax'"
adb shell am force-stop com.ironhsp.hsp3dx
adb shell am start -n com.ironhsp.hsp3dx/android.app.NativeActivity

起動時に files/start_override.ax があれば assets の start.ax より優先されます。

制限事項

• Cookie 永続化・Basic 認証ヘルパ未実装
• HTTP レスポンスヘッダ個別取得 (dx_http_get_res_header) は Win 版のみ
• 画面回転時のリロード未対応 (アプリが再起動される)

12. リファレンス

同梱ドキュメント

• hsp3dx_spec.html — 仕様書 (アーキテクチャ・クロスプラットフォーム設計の詳細)
• hsp3dx_spec.md — 上記の Markdown 版

ヘルプファイル (HSP エディタ連携)

• package/hsphelp/iron_dxlib.hs — 手書き 73 命令の日本語詳細解説
• package/hsphelp/iron_dxlib_auto.hs — 自動生成 1650 命令の索引 + 原関数シグネチャ

サンプル

すべて hsp3dx/samples/ にあります。全 25 本、コンパイル済 .ax も同梱。

外部リンク

• DxLib 公式関数リファレンス
• picojson (JSON パーサのベース実装)

Phase M — プラットフォーム統合機能 (2026-04-22)

モバイル OS のライフサイクル/設定永続/デバイス制御を統一 API で提供する一連のコマンド群。Win/iOS/Android 共通シグネチャで、対応機能のないプラットフォームは無害な no-op か stub 値を返します。

M.1 — exec / dialog

標準 HSP と同名で、モバイル対応版に差し替え。

exec "https://example.com"            ; Win=ShellExecute / iOS=UIApplication.open / Android=Intent
exec "mailto:foo@example.com"

dialog "削除しますか？", 2, "確認"     ; mode 2 = Yes/No
if stat = 1 : mes "Yes 選択"

dialog の戻り値 stat: 1=OK/Yes、2=Cancel/No、3=Cancel (mode 3 のみ)。

M.2 — dx_pref_* (設定の永続保存)

セクション + キーで値を保存する Key-Value ストア。Win は EXE 同名 .ini、iOS は NSUserDefaults、Android は SharedPreferences にマップ。

dx_pref_set_str  "General", "username", "alice"
dx_pref_set_int  "General", "launch_count", 42
dx_pref_set_double "Audio", "volume", 0.75

dx_pref_get_str  "General", "username", name, "anon"
dx_pref_get_int  "General", "launch_count", 0
v = stat

dx_pref_exists   "General", "username"    ; stat=1/0
dx_pref_list_keys "General", keys         ; 改行区切り、stat=件数
dx_pref_remove   "General", "username"
dx_pref_clear    ""                        ; 全消去

M.3 — onevents (アプリライフサイクル)

OS 通知をフックして HSP ラベルへ gosub 相当で飛ばす。

onevents DX_EVT_APP_BACKGROUND,    *on_bg
onevents DX_EVT_APP_FOREGROUND,    *on_fg
onevents DX_EVT_ORIENTATION_CHANGED, *on_rot

*on_bg
  ; バックグラウンドへ遷移 (セーブ処理等)
  return

定義済イベント: APP_BACKGROUND (0), APP_FOREGROUND (1), APP_WILL_TERMINATE (2), APP_LOW_MEMORY (3), ORIENTATION_CHANGED (4)。iOS=NSNotificationCenter、Android=Application.ActivityLifecycleCallbacks + ComponentCallbacks2 で購読。

M.4 — dx_dev_* 基本 (権限不要)

dx_dev_vibrate 200             ; 200ms バイブ (Android は VIBRATE 権限)
dx_dev_is_dark                  ; stat=1/0
dx_dev_battery lv, bs           ; 残量%、状態 (0/1/2/-1)
dx_dev_orientation              ; stat=0..3
dx_dev_sound 1104               ; iOS SystemSoundID (他 OS は短ビープ)

M.5 — dx_dev_* センサー

初回呼び出し時に自動 start、以降は最新値を取得する方式。

dx_dev_accel    ax, ay, az        ; 加速度 (iOS=g単位、Android=m/s²)
dx_dev_gyro     gx, gy, gz        ; 角速度 (rad/s)
dx_dev_attitude roll, pitch, yaw  ; 姿勢 (radian)

M.6 — dx_dev_* 権限要 (GPS / トーチ)

dx_dev_gps_start                   ; 初回は OS が権限プロンプト
dx_dev_gps_status                   ; 0=未開始 / 1=要求中 / 2=稼働 / 3=denied
dx_dev_gps_get lat, lng             ; 未 fix 時 0, 0

dx_dev_torch_supported              ; stat=1 対応 / 0 非対応
dx_dev_torch 1                      ; ON
dx_dev_torch 0                      ; OFF

iOS: NSLocationWhenInUseUsageDescription を Info.plist に記載必須。Android: ACCESS_FINE_LOCATION / CAMERA を AndroidManifest に記載 + 実行時権限要求。

M.8 — マイクレベル

マイクからの瞬間音量を RMS で 0〜100 に正規化した数値で取得します(録音データ自体は保存されません)。

dx_dev_mic_start          ; 初回で OS 権限プロンプト (RECORD_AUDIO / Microphone)
repeat 100
    dx_dev_mic_level      ; stat = 0..100 (-1=未開始)
    mes "level: " + stat
    await 100
loop
dx_dev_mic_stop

iOS: AVAudioRecorder を /dev/null に record 開始 + averagePowerForChannel。Android: AudioRecord + 別スレッドで RMS 連続計算。

M.9 — 生体認証 (iOS のみ)

dx_dev_biometric_auth "ログイン認証のため"
if stat = 1 : mes "成功"
if stat = 0 : mes "失敗/キャンセル"
if stat = -1 : mes "未対応デバイス"

iOS は LAContext.evaluatePolicy(DeviceOwnerAuthenticationWithBiometrics) を dispatch_semaphore で同期化。Info.plist に NSFaceIDUsageDescription が必要。Android は AppCompat 依存を避けるため現状 stub (常に -1)。

M.x 未実装 (今後の予定)

• カメラ撮影 (intent / AVCaptureSession)
• Android 生体認証 (BiometricPrompt / androidx.biometric 導入時)

IronHSP Project / hsp3dx Phase M guide — 最終更新 2026-04-22