チュートリアル

このチュートリアルでは、サンプルプロジェクトを開き、スクリプトコンポーネントを作成し、最初のゲームをビルドする手順を説明します。

1. エディターを起動

zig build run

Turian Studio がデフォルトのシーン（地面、カメラ、方向光）とともに開きます。

2. サンプルプロジェクトを開く

1. ファイル → プロジェクトを開く… を選択します。
2. examples/basic-project/ に移動して確認します。
3. アセットブラウザにプロジェクトの assets/ フォルダーが表示されます。
4. scene-01.prefab をダブルクリックしてシーンを読み込みます。

3. エディターのレイアウト

┌──────────────┬──────────────────────┬────────────────┐
│ シーン        │    シーンビュー       │   インスペクター│
│ ヒエラルキー  │   (3D ビューポート)  │                │
├──────────────┴──────────────────────┴────────────────┤
│                  アセットブラウザ                      │
└───────────────────────────────────────────────────────┘

• シーンヒエラルキー — すべてのゲームオブジェクト。クリックして選択、ドラッグして並べ替え。
• シーンビュー — リアルタイム 3D プレビュー（SDL3 GPU — Vulkan/Metal/D3D12）。
• インスペクター — 選択したオブジェクトの Transform およびコンポーネントフィールドを編集。
• アセットブラウザ — assets/ をブラウズ。.prefab シーンファイルをダブルクリックして開く。

4. ゲームオブジェクトを追加

1. シーン → 空のオブジェクトを追加（またはメニュー項目をクリック）。
2. ヒエラルキーでそれを選択します。
3. インスペクターで Transform を展開し、位置を (0, 1, 0) に設定します。
4. コンポーネントを追加 ▾ → MeshRenderer をクリックします。

5. スクリプトコンポーネントを作成

プロジェクトフォルダー内に assets/spinner.zig を作成します：

const engine = @import("engine");

pub const Spinner = struct {
    /// Marks this struct as a component the editor should discover.
    pub const is_component = true;

    /// Rotation speed in degrees per second (editable in Inspector).
    speed: f32 = 90.0,

    pub fn awake(self: *Spinner) void {
        _ = self;
        @import("std").debug.print("[Spinner] awake\n", .{});
    }

    pub fn update(self: *Spinner, time: engine.Time) void {
        _ = self.speed * time.delta; // apply rotation once scene API lands
    }
};

重要なルール：

• 構造体内に pub const is_component = true; を追加して、発見対象としてマークします。エディターは Zig ソースを解析し（正規表現ではありません）、フォーマット、コメント、条件付きコンパイルに関係なくマーカーが機能します。false に設定すると、一時的に構造体を除外できます。
• 構造体は pub であり、名前が大文字で始まる必要があります。
• 各コンポーネントの型名はプロジェクト全体で一意である必要があります。重複は報告され、2 つ目は無視されます。
• サポートされているフィールド型：f32、i32、bool、engine.Vec3、engine.GameObjectRef、engine.ComponentRef、engine.AssetRef。

アセットブラウザのヘッダーにある更新ボタンをクリックして新しいスクリプトを認識させ、コンポーネントを追加 ▾ から Spinner を追加します。

6. スクリプトのライフサイクルフック

すべてのフックはオプションです。必要なものだけを実装します：

すべてのフックは第 2 パラメーターとして frame: engine.Frame も受け付けます。update(self, frame: engine.Frame) を使用して、入力、サービス、および完全なシーンコンテキストにアクセスします。入力システムガイドを参照してください。

engine.Time フィールド（frame.time としても利用可能）：

• .delta — 前回のフレームからの経過秒数（f32）
• .elapsed — シーン開始からの合計秒数（f32）
• .frame — フレームカウンター（u64）

FPS カウンターの例

const std    = @import("std");
const engine = @import("engine");

pub const FpsDisplay = struct {
    pub const is_component = true;

    _timer: f32 = 0,

    pub fn update(self: *FpsDisplay, time: engine.Time) void {
        self._timer += time.delta;
        if (self._timer >= 1.0) {
            self._timer -= 1.0;
            const fps = if (time.delta > 0) 1.0 / time.delta else 0.0;
            std.debug.print("FPS: {d:.0}\n", .{fps});
        }
    }
};

オブジェクト参照の例

const engine = @import("engine");

pub const Follower = struct {
    pub const is_component = true;

    /// Drag a game object from the Hierarchy onto this field.
    target: engine.GameObjectRef = .{},

    pub fn start(self: *Follower) void {
        const name = self.target.slice();
        if (name.len > 0) {
            @import("std").debug.print("[Follower] following '{s}'\n", .{name});
        }
    }
};

7. シーンを保存

ファイル → シーンを保存 で assets/scene-01.prefab に書き込みます。これは人間が読める JSON ファイルであり、差分を確認して Git にコミットできます。

8. ゲームをビルド

エディター経由

ビルド → ゲームをビルド で、プロジェクトフォルダー内の .cache/zig-out/bin/game にスタンドアロン実行ファイルをコンパイルします。

CLI 経由

zig build cli -- build path/to/my-project

またはインストール済みのバイナリを使用：

turian-cli build path/to/my-project
turian-cli new-project ../my-new-game "My Game"   # プロジェクトを作成
turian-cli info        path/to/my-project         # メタデータを表示

9. 数学ライブラリの使用

const math = @import("engine").math;

const pos = math.Vector3{ .x = 0, .y = 1, .z = 0 };
const rot = math.Quaternion.fromAxisAngle(math.Vector3.up(), 45.0);
const m   = rot.toMatrix4();
const col = math.Vector3i{ .x = 255, .y = 128, .z = 0 };  // integer vector

使用可能な型：Vector2、Vector3、Vector4、Vector2i、Vector3i、Vector4i、Matrix4、Quaternion。

次のステップ

• インストール / ソースからビルドを読んで、完全な開発者セットアップを確認してください。
• [examples フォルダー]({{ site.Params.Repo }}/-/tree/main/examples)で、より完成度の高いプロジェクトテンプレートを参照してください。
• 入力システムガイドを参照して、アクションマップ、ゲームパッドサポート、ランタイムリバインディングを追加してください。
• インスペクターでコンポーネントフィールドのリファレンスを確認してください。フィールドラベルにマウスを乗せると型情報が表示されます。

← すべてのドキュメント このページを編集