見た目(visual.js)の仕様

見た目(visual.js)は、ルールの状態を3Dの絵にするファイルです。絵はThree.jsで描きます。ルールの書き方はルール(game.js)の仕様にあります。

見た目は勝ち負けに関わりません。ルールと違って、ふつうのJavaScriptで書けます。端末ごとに違う絵になってもかまいません。

1. 全体の形

visual.js はモジュールで、次の関数を export します。

export function init(ctx) { … }            // 必須。最初に1回
export function update(snapshot, dt) { … } // 必須。絵を描くたび
export function resize(ctx) { … }          // 任意。画面の大きさが変わったとき
export function preview(v, dt) { … }       // 任意。見た目の変更の画面で、選んだものを見せる

let THREE, ctx, ball;

export function init(c) {
  ctx = c;
  THREE = c.THREE;
  ctx.scene.background = new THREE.Color(0x8ecae6);
  ball = new THREE.Mesh(new THREE.SphereGeometry(0.5, 24, 16),
                        new THREE.MeshStandardMaterial({ color: 0xff6633 }));
  ctx.scene.add(ball);
}

export function update(snapshot, dt) {
  const s = snapshot.state;
  ball.position.set(ctx.toWorld(s.ballX), 0.5, ctx.toWorld(s.ballZ));
}

1.1 試合をまたいで使われる

visual.js は、ゲームの箱を開いてから閉じるまで、同じものが使われます。同じページで続けて遊ぶと、次の試合でも読み込み直されず、init も呼ばれません。

• 席(snapshot.myRole)、表示名、見た目の選択(snapshot.looks)は、試合ごとに変わることがあります。init や最初の update で一度読むのではなく、毎回 snapshot を見ます(3.1)
• 試合の前にも、vsboxが描画を準備するために update を呼びます(myRole は null)。CPUで少し進めた状態と、そのあいだの出来事(effects)も届きます。最初の update を、試合の始まりと思わないでください
• 前の試合や準備のときに作った物(飛んでいる粒子など)は残ります。要らなければ自分で片付けます
• 試合が変わったかは snapshot.match(試合ごとに1ずつ増える番号)で分かります。同じ席で続けて遊ぶこともあるので、席の変化では見分けられません。基本は、いまの snapshot に合わせて絵を直す書き方にします

1.2 エンティティの絵を、いまのエンティティに合わせる

エンティティの id は、ラウンドが始まるたびに "e1" から振り直されます。試合が変わっても同じです。id で絵を覚えるときは、毎回いまのエンティティと突き合わせて、無くなったものを消し、kind が変わったものは作り直します。

let THREE = null;
let ctx = null;
const shown = new Map();   // id → { kind, mesh }
let ball = null;
const paint = {};

export function init(c) {
  ctx = c;
  THREE = c.THREE;
  ball = new THREE.SphereGeometry(0.3, 16, 12);             // 形と材質は1回だけ作って使い回す(8)
  paint.coin = new THREE.MeshStandardMaterial({ color: 0xffcc33 });
  paint.other = new THREE.MeshStandardMaterial({ color: 0x88aacc });
}

export function update(snapshot, dt) {
  const alive = new Set();
  for (const e of snapshot.entities) {
    alive.add(e.id);
    let s = shown.get(e.id);
    if (s && s.kind !== e.kind) {          // 同じ id でも、別の物になっていたら作り直す
      ctx.scene.remove(s.mesh);
      s = null;
    }
    if (!s) {
      const mesh = new THREE.Mesh(ball, e.kind === "coin" ? paint.coin : paint.other);
      ctx.scene.add(mesh);
      s = { kind: e.kind, mesh: mesh };
      shown.set(e.id, s);
    }
    s.mesh.position.set(ctx.toWorld(e.x), 0.3, ctx.toWorld(e.z));
  }
  for (const [id, s] of shown) {
    if (!alive.has(id)) {                  // いまは無いもの(消えた・ラウンドが変わった)を片付ける
      ctx.scene.remove(s.mesh);
      shown.delete(id);
    }
  }
}

1.3 動く場所

見た目は、ゲームの本体とは別の場所(Worker)で動きます。

• 画面の部品(DOM)には触れません。文字も3Dの中に描きます(5. 文字を出す)
• 通信はできません(fetch なども使えません)
• import は使えません。Three.jsは ctx.THREE を使います
• 指の位置は読めません。指で動かすものは、ルールが g.state に置いた値を描きます

init・update・resize でエラーが出ると、見た目はそこで止まります。試合中なら試合も止まり、結果の板に理由が出ます。見た目が12秒以上返事をしない(無限ループなど)ときも同じです。

2. ctx

init と resize に渡されるものです。

持ち込んだファイルは、あとから足したり消したりできます。無いときに null が返ることを前提に書きます。

3. 既定の場面

vsboxは、何も書かなくても絵が出るように、場面を用意してから init を呼びます。どれも作者が変えてかまいません。

• 長さは、ルールの1000が場面の1です(ctx.toWorld)
• カメラの距離は、画面の縦横比で変わります。霧のように距離で効くものは、ctx.cameraDistance を基準にします
• 画面の大きさや向きが変わると、vsboxはカメラを既定の位置に置き直してから resize を呼びます。カメラを動かすゲームは、resize でもう一度置きます

3.1 player2 に反対側から見せる

vsboxが決めた距離と角度はそのまま使い、位置の符号だけ変えます。ルールの側でも、指の向きを直します(ルール(game.js)の仕様 6.5)。

let ctx = null;
let role = null;

// 席に合わせてカメラを置く。player2 は反対側(z が負)、それ以外は vsbox の既定の側(z が正)
function faceMySide() {
  const z = Math.abs(ctx.camera.position.z);
  ctx.camera.position.z = role === "player2" ? -z : z;
  ctx.camera.lookAt(0, 0, 0);
}

export function init(c) { ctx = c; }

export function resize(c) {
  ctx = c;
  faceMySide();      // vsbox がカメラを既定の位置に戻したあとなので、もう一度置く
}

export function update(snapshot, dt) {
  if (snapshot.myRole !== role) {   // 席は試合ごとに変わることがある(1.1)
    role = snapshot.myRole;
    faceMySide();
  }
}

4. snapshot

update に渡されるものです。中身は写しなので、書き換えてもルールには影響しません。

• update が呼ばれる回数は、ルールが進む回数と同じとは限りません。同じ snapshot が続けて来ることも、間が飛ぶこともあります。時間で動く演出は dt で進めます
• 物理の体を描くときは、poses を使うと動きがなめらかです(entities の値は1000分の1きざみの整数)
• state には2人ぶんが入っています。体力や持ち物のように本人のぶんだけ出すものは、myRole で選びます

4.1 出来事 snapshot.effects

ルールの g.effect(name, data) が、一度だけ届きます。次のフレームでは空になります。爆発の粒子や得点の演出は、ここで作ります。

for (const fx of snapshot.effects) {
  if (fx.name === "explode") { spawnSparks(fx.data.x, fx.data.z); }
}

音は見た目では鳴らしません。ルールの meta.sounds に出来事の名前と音を書くと、vsboxが鳴らします(ルール(game.js)の仕様 4.8)。

4.2 名前 snapshot.names

本人がマイページで決めた表示名です。決めていない人とログインしていない人は null です。試合の前の描画の準備とサムネイルでは、両方 null です。CPUは相手の名前(meta.opponents が無ければ "CPU")です。

• null のときに何と出すか(「あなた」「相手」など)は、作者が決めます
• 人が打った文字です。絵に描いて出す以外には使わないでください

4.3 見た目の選択 snapshot.looks

meta.looks(ルール(game.js)の仕様 4.7)で決めた欄ごとに、選ばれた選択肢の id が入っています。選んでいない人の欄も、標準で埋まっています。宣言していなければ {} です。

snapshot.looks.dice    // { player1: "red", player2: "white" }   owner が "each" の欄
snapshot.looks.table   // "felt"                                 owner が "player1" か "player2" の欄

4.4 端末 snapshot.device

遊んでいる端末が、指で操作する端末("mobile")か、マウスとキーボードの端末("pc")かです。見分け方は、一覧に出すかどうか(ルール(game.js)の仕様 4.5)と同じです。

スマホとパソコンの両方で遊べるゲーム(meta.devices: "both")で、端末によって絵を変えたいときに使います。変えるかどうかは自由です。

stick.visible = snapshot.device === "mobile";   // 例:画面のスティックは、指の端末でだけ描く

• 見た目は端末ごとに違ってよいので、2人で描くものが違っても試合はずれません
• 見えなくしても、その場所をマウスで押せば今までどおり指として届きます(ルールは指の位置を読むので)
• 読まなくてもかまいません。読まなければ、どの端末でも同じ絵になります

4.5 間を補う snapshot.prev snapshot.alpha

ルールの meta.interpolate を true にすると(ルール(game.js)の仕様 4.9)、絵がルールの進む回数より多く描かれます。そのままでは同じ姿が続けて描かれるだけなので、1つ前の状態(prev)と今の状態の間を、割合(alpha)で補って描きます。

const a = snapshot.alpha;
const before = snapshot.prev.state.ballX;
const now = snapshot.state.ballX;
ball.position.x = ctx.toWorld(before + (now - before) * a);

物理の体(snapshot.poses)は、位置と一緒に向き(四元数)も混ぜます。一度に大きく跳んだものと、新しく出てきたものは、補わずに今の姿で置きます。

const qa = new THREE.Quaternion();   // 使い回す
const qb = new THREE.Quaternion();

function placeBodies(snapshot) {
  const t = snapshot.alpha;
  const was = new Map(snapshot.prev.poses.map((p) => [p.id, p.pose]));
  for (const p of snapshot.poses) {
    const mesh = meshes.get(p.id);
    const b = p.pose;
    const a = was.get(p.id);
    // 1回(1/30秒)で動けるより遠くへ跳んだ:補わない
    if (!a || Math.hypot(b.x - a.x, b.y - a.y, b.z - a.z) > 3) {
      mesh.position.set(b.x, b.y, b.z);
      mesh.quaternion.set(b.qx, b.qy, b.qz, b.qw);
      continue;
    }
    mesh.position.set(a.x + (b.x - a.x) * t, a.y + (b.y - a.y) * t, a.z + (b.z - a.z) * t);
    // slerpQuaternions は、近いほうの回り方で混ぜる
    mesh.quaternion.slerpQuaternions(qa.set(a.qx, a.qy, a.qz, a.qw), qb.set(b.qx, b.qy, b.qz, b.qw), t);
  }
}

• alpha は、0 のとき prev の時点、1 のとき今の状態の時点です。補って描くと、見える姿は最大でルールの1回ぶん(1/30秒)前になります
• prev はいつも入っています。試合の最初と、試合の前の描画の準備、サムネイルでは、今の状態そのものです
• meta.interpolate を宣言していないとき、描くのが間に合わずに1秒30回へ戻したとき、試合の前と決着のあとは、alpha はいつも 1 です
• ラウンドが変わって初めの位置に戻るなど、一度に大きく跳んだものを補うと、間を滑って見えます。補うかどうかは、見た目のコードで決めます
• 1つ前の状態に無かったもの(新しく出てきたもの)は、補えません。今の状態のまま描きます
• エンティティの id は振り直されることがあります(1.2)。prev と id で突き合わせるときは、同じものかどうかも確かめます

5. 文字を出す

見た目からは画面の部品(DOM)に触れないので、文字は絵に描いて板に貼ります。

1. OffscreenCanvas に文字を描く
2. THREE.CanvasTexture にする
3. 板(PlaneGeometry)に貼る
4. 板をカメラの子にする(カメラが動いても、画面の同じ場所に留まる)

注意 カメラは最初、場面に入っていません。子を足したら ctx.scene.add(ctx.camera) が要ります。入れないと、子は描かれません。

• 板の大きさは、カメラの画角と距離から計算します。決めた大きさにすると、縦横比の違う端末で画面の外に出ます
• 文字の後ろに下地を敷きます。文字の色だけで読ませると、背景の色によっては読めなくなります
• 文字を書き換えたときだけ描き直します。毎フレーム描き直すと、そのたびに絵をGPUへ送り直すので、とても重くなります
• 3・2・1(countLeft)やラウンドの区切り(breakLeft)も、見た目が描きます。vsboxは時間を止めるだけです

6. 見た目の変更の見本 preview(v, dt)

meta.looks を宣言したゲームで、選んでいるものを動かして見せるための関数です。書かなければ、見た目の変更の画面には、選択肢と説明だけが出ます。

書くと、見た目の変更の画面を開いている間、update の代わりに毎フレーム呼ばれます。

• x・y は枠の左上からのpx、ndc は-1〜1の値で、Three.jsの Raycaster.setFromCamera にそのまま渡せます

const ray = new v.THREE.Raycaster();
for (const t of v.taps) {
  ray.setFromCamera(t.ndc, v.camera);
  const hit = ray.intersectObjects(v.scene.children, true)[0];
  if (hit) { /* hit.object を触った */ }
}

• 物は v.scene に新しく作ります。試合の場面の物を足すと、試合の場面から抜けてしまいます。形・材質・テクスチャは試合と使い回してかまいません

7. 持ち込んだファイル

画像・音・3Dモデルは、開発者タブの作品のページで置きます。同じ名前があれば置き換えます。

• 1つの作品に置けるのは、合計20MB・64個まで。画像の画素数は、全部あわせて縦×横32M画素ぶんまで
• 音は全部あわせて、展開したあとの大きさで24MBまでです(ルール(game.js)の仕様 4.8)
• 大きさ・長さ・画素数は、置くときに確かめます。超えるものは断られます(遊ぶときに初めて分かる、ということはありません)
• 素材は遊ぶ前にまとめて読み込みます。多いほど「準備中…」が長くなります(1MB を超えると、読み込んだ割合が出ます)。読み込めなかった素材があると、作品の箱に名前と理由が出ます
• 名前は英小文字・数字で始まり、英小文字・数字・. _ - だけ、40文字まで
• 中身も確かめます。拡張子だけ変えたファイルは断られます

7.1 画像

ctx.texture(name) で、材質に貼れるテクスチャになります。

const mat = new THREE.MeshStandardMaterial({ map: ctx.texture("tile.png") });

7.2 3Dモデル

.glb だけを置けます。ctx.model(name) は読み込んだglTF(.scene と .animations)を返します。

const gltf = ctx.model("hero.glb");
if (gltf) {
  const a = ctx.clone(gltf.scene);   // 1体目
  const b = ctx.clone(gltf.scene);   // 2体目
  ctx.scene.add(a, b);
}

注意 2体目以降は、必ず ctx.clone で作ります。Three.jsの clone() は骨を共有するので、骨のあるモデルでは2体が同じ動きになります。

置けるモデルには、次の決まりがあります。

• すべて1つのファイルに埋め込む(外部のファイルを指すモデルは断られる)
• 使える拡張機能は KHR_materials_unlit・KHR_texture_transform・KHR_materials_emissive_strength だけ(Draco・KTX2・meshoptで圧縮したものは断られる)
• ノード2000・メッシュ500・プリミティブ2000・埋め込み画像20枚まで
• 頂点や索引などのデータの要素は、合計4,000,000まで
• アニメーションのデータは8MBまで。キーの数1つを16バイトとして見積もります(どの種類のキーも同じ)
• 埋め込み画像の大きさは、持ち込む画像と同じ(縦×横4096×4096画素ぶんまで、1辺8192画素まで)

ファイルが8MB以下でも、これらを超えると断られます。

8. 軽く描くために

開発者タブの「開発者として開く」で遊ぶと、画面の隅にfpsなどの数字が出ます。「転送」は1秒あたりの、絵(キャンバスや画像)のテクスチャの送り直しです。骨のある3Dモデルが動くたびに送る骨の位置は、数えません。ほぼ毎フレーム起きていると、試合の最初の20秒で ⚠ が付きます。中身が変わらないのに毎回描き直している絵があります。