シーンの読み取りとプレイカメラ

SDK 1.3 では 2 つの機能が追加されます。

メンバー	役割
host.Scene	シーンアクター (カメラ・パス・トリガーゾーン・表示 …) を読み取ります。
host.View	プレイ状態と時計を読み取り、プレイ中にビューポートのカメラを動かします。

これにより、プレイのプレビューでカメラ演出 (軌道・ズーム・パス追従) を作れます。plugin.json には "sdk": "^1.3" を書きます。エディター 0.9.1 以上が必要です。

シーンアクター: INpScene

メンバー	型	説明
Actors	IReadOnlyList<NpSceneActor>	すべてのシーンアクター (アウトライナーの順)。呼び出すたびに現在のワールドから読み直したコピーです。
Find(string id)	NpSceneActor?	id で検索。なければ null

public sealed record NpSceneActor(string Id, string Kind, string Name, NpVec3 Pos, NpVec3 Rot, NpVec3 Size, string PropsJson = "{}");

項目	説明
Id	アクター id (ワールドロジックが使う名前)
Kind	種類 (camera ・ path ・ trigger ・ blocker ・ display ・ text ・ spawn ・ light ・ sound …)
Name	アウトライナーに表示される名前
Pos	位置 (ワールド座標、ブロック 1 マス = 1)
Rot	(yaw, pitch, roll) Minecraft の度
Size	トリガーゾーン・ブロッカーボックスならボックスのサイズ、それ以外ならサイズ倍率
PropsJson	プロパティオブジェクトの JSON 文字列。なければ "{}"

• 作成時の状態です。プレイ中にアニメーションで動いた姿勢ではありません。
• アクターが多いと Actors は重くなります。PlayTicked の中で毎回呼び出さず、プレイ開始時に 1 回読み込んでおきます。
• PropsJson は System.Text.Json で読み取ります。例: カメラの fov、パスの points (ワールド座標 [[x,y,z],…])。

角度のルール

値	意味
yaw 0	+Z (南) を向く
yaw 90	−X (西) を向く
pitch 0	水平
pitch 90	下を向く

Minecraft の F3 画面の角度と同じルールです。NpSceneActor.Rot と INpView の角度は同じルールを使います。

foreach (var a in host.Scene.Actors)
    if (a.Kind == "camera") host.Log($"{a.Id} {a.Name} {a.Pos} yaw {a.Rot.X} pitch {a.Rot.Y}");

if (host.Scene.Find("route") is { } path)
{
    using var doc = System.Text.Json.JsonDocument.Parse(path.PropsJson);
    // doc.RootElement.GetProperty("points") …
}

ビューポート・プレイ: INpView

メンバー	型	説明
Playing	bool	プレイまたはシミュレート中かどうか
PlayTime	double	プレイの時計 (秒)。開始 = 0、一時停止中は停止。プレイ中でなければ 0
CameraPos	NpVec3	現在のカメラ位置
CameraYaw ・ CameraPitch	float	現在のカメラ角度 (Minecraft の度)
CameraFov	float	現在の視野角 (度)
SetCamera(NpVec3 pos, float yaw, float pitch, float fov = 0)	bool	カメラをその位置・向きへ。成功すると true
LookAt(NpVec3 target, float fov = 0)	bool	現在の位置 (このプラグインが最後に置いた位置) から target を見る
LookAt(NpVec3 eye, NpVec3 target, float fov = 0)	bool	eye から target を見る
ReleaseCamera()	void	このプラグインによるカメラ移動を解除 (元の視点に戻る)
PlayChanged	event Action<bool>?	プレイ開始 (true)・終了 (false)
PlayTicked	event Action<double>?	プレイの時計の 1 ティック (0.05 秒) ごと。値 = 経過秒数

カメラ移動のルール

ルール	内容
有効な場面	プレイ・シミュレート中のみ。それ以外では false を返し、何も起きません。
動き	1 回呼び出すとその位置に置きます。動かすには PlayTicked で毎ティック呼び出します。
一人称の体	カメラを動かしている間、プレイの体は停止します。
fov	0 以下 = 現在の視野角のまま。それ以外は 30 〜 110 度に収めます。
不正な値	無限大・NaN の位置、目と目標が同じ LookAt は false
元に戻る	ReleaseCamera() ・プレイ停止 (Esc)・プラグインの無効化・隔離のときに、元の視点 (プレイ = 体の目の位置、シミュレート = 自由カメラ) と視野角に戻ります。
複数が保持するとき	内蔵アクション cinematic のプレビューと同じ経路を使います。同じティックに複数が動かした場合は、後から指定したものが優先されます。

例: プレイ中の 6 秒間の軌道カメラ

コンソールで myorbit と入力すると、(0, 70, 0) の周りを 6 秒間回ります。

double t = 0; bool on = false;

host.AddCommand(new NpCommand("myorbit", "myorbit", "플레이 중 6초 궤도 카메라", _ =>
{
    if (!host.View.Playing) return "먼저 플레이를 시작하세요";
    on = true; t = 0; return "시작";
}));

host.View.PlayChanged += playing => { if (!playing) on = false; };
host.View.PlayTicked += dt =>
{
    if (!on) return;
    t += dt;
    var c = new NpVec3(0, 70, 0);
    var eye = new NpVec3(c.X + 30 * (float)Math.Cos(t), 85, c.Z + 30 * (float)Math.Sin(t));
    host.View.LookAt(eye, c, fov: 60);
    if (t > 6) { on = false; host.View.ReleaseCamera(); }
};

例: シーンのカメラアクターでズーム

host.View.PlayTicked += dt =>
{
    if (!_running) return;
    _t += dt;
    var cam = host.Scene.Find("cam_zoom_1");
    if (cam == null) { _running = false; return; }
    host.View.SetCamera(cam.Pos, cam.Rot.X, cam.Rot.Y, fov: 70 - (float)_t * 5);   // 視野角を狭めてズーム
    if (_t > 6) { _running = false; host.View.ReleaseCamera(); }
};

ヒント / 注意

• PlayTicked は 0.05 秒ごとに呼ばれます。軽い処理にしてください。
• 内蔵アクション cinematic が既にカメラ演出 (複数のカメラ・パス・滞在・移動) を行います。同じ type 名を AddSceneEvent で登録すると内蔵と重なり、プラグインが有効になりません。独自に演出する場合は type を登録せず、Scene ・ View だけを使います。
• カメラ演出はエディターのプレビュー用です。ゲームサーバーのカメラはサーバープラグインが担当します。
• シーンアクターを作成したり移動したりする API はまだありません。読み取りのみです。

関連ドキュメント

• ホスト API
• ワールドロジック type の追加
• プレイでテスト
• シーンアクターとアウトライナー
• シーケンサー