referenceupdated v2growing

Rubbing — 仕様書

単一 HTML で動くジムカーナゲーム「Rubbing」の設計仕様。物理・モード・ゴースト・シード収集・テーマ・アーキテクチャを定める。

Rubbing — 仕様書

0. 概要

Rubbing はブラウザで動く 2D ジムカーナゲーム。単一 HTML として配布でき、file:// からも開ける。ライバルは常に「昨日の自分」。育成要素はなく、上達はプレイヤーの腕のみに帰着する。

  • ジャンル: 2D トップダウン・ジムカーナ
  • 操作: タッチ(ステアリング・ペダル)/キーボード
  • モード: TIME ATTACK と AI BATTLE の 2 つのみ
  • テーマ: Paper Kit(明るい紙の上に Material 風の物体が置かれている)
  • 配布: 単一 HTML(bundle/index.html)
  • 開発: 分割ソース + bundle/split 方式(2026-09-28-html-split-bundle-規約 に従う)
  • リンク: rubbing

1. 設計思想

1.1 コアループ

BATTLE ──▶ 未知のシードと遭遇 ──▶ シード登録
↑ │
│ ▼
│ TIME ATTACK
│ │
└── ゴーストが強くなる ◀── PB更新でゴースト保存
  • BATTLE = 探索。次々と新シードに出会う場。敗北してもシードは登録される。
  • TIME ATTACK = 研磨。登録済みシードを、自分のベストゴーストと走って削る場。
  • 両モードとも、最終的には「過去の自分」と走る。これが設計の核。

1.2 大原則

原則内容
コースは不変、変数は自分だけ同じシードの再走でしか上達を実感できない → シードの再走可能性が最重要
リアリティ重視ラバーバンド、スリップストリーム、燃料、タイヤ摩耗などの「ごまかし」は入れない
育成禁止パラメータ上昇・アンロック車両・スキルツリーは無し
数字で自分を可視化ゴースト、デルタ、セクタータイム、メダル
摩擦感覚の重視3 段階の路面 μ と、その視覚言語を明確に

1.3 捨てるもの(明確に)

  • ラバーバンド / スリップストリーム / 燃料 / タイヤ摩耗
  • 車両アンロック / スキルツリー / 経験値
  • オンラインランキング(オフライン前提)
  • 3 モード以上

2. モード

2.1 TIME ATTACK

  • 所持シードを一覧から選んで走る。
  • ライバルは常に 自分のベストゴースト 1 本。
  • PB を更新するとゴーストが差し替わる。
  • 画面上部はコース俯瞰(fit view)、下部は追跡視点(chase view)。

2.2 AI BATTLE

  • ステージを連続クリアしていく。各ステージが新シード。
  • ライバルは以下を優先順に選ぶ:
    1. そのシードの自分のベストゴースト
    2. そのシードの敗北ゴースト(未クリア時)
    3. スキル段階付きボット
  • 勝てば次ステージへ、負ければラン終了。敗北時もシードは登録。
  • 画面上部はライバル追跡視点、下部は自車追跡視点。
  • Bot スキルは stageIndex に応じて線形に上昇(BOT.skillBase → BOT.skillMax)。

2.3 共通

  • カウントダウン 3.2s。カウント中に throttle > 0.85 で PERFECT LAUNCH(1.5s のブースト)。
  • パイロン接触で即 MISS(GAME.hitR + パイロン半径)。
  • ゴールでクリア。TA はメニューへ、Battle は次ステージへ。
  • ニアミス(GAME.nearMissDist 未満)で CLOSE 表示(タイムには影響しない)。

3. ゴースト・シード

3.1 ゴースト保存

  • シードごとに 上位 3 本 を保持(gk:ghost:v3:{seed})。既定は 1st。
  • 敗北ゴーストは別キー(gk:defeat:v3:{seed})。
  • エンコード: x, y, ang, gates を 8 byte/サンプルで Int16/Uint8 パック → base64。
  • サンプルレート 30 Hz(GHOST.rate)。
  • サンプル数は maxStored を超えると古いものから捨てる。

3.2 ゴースト表示

  • 半透明の車体(COLORS.ghostCar)+ 点線枠。
  • TA では「ベストライン」として点線ガイドも描画。
  • TA/Battle どちらでも並走する。
  • 描画優先度は自車・ライバルの下、道路の上。

3.3 シード

  • runSeed から hashSeed(runSeed, stageIndex) で決定論的に生成。
  • 一度でも走ったシードは profile.seedOrder に登録され、COLLECTION から再走可能。
  • シードの表示は 16 進 8 桁(先頭 6 桁のみ表示)。

4. セクター・デルタ・メダル

4.1 セクター

  • 1 コースを SECTOR.count = 4 分割。
  • 各境界ゲート通過時にスプリットを計測。
  • ゴーストのセクター通過時刻と比較し、S1 +0.42 のように表示(#sector-pop)。
  • 表示色: 先行 = 緑(#4a9e4a)、後退 = 朱(#e85a32)。

4.2 デルタバー

  • 画面上部中央に横棒で ±1.5s を可視化(DELTA.window)。
  • 中央 = 同着、左 = 先行(緑)、右 = 後退(朱)。
  • 数値は ±X.XX で小さく表示。
  • ゴースト未保存の初回は -- を表示。

4.3 メダル

  • コース全長から par time を推定し、その倍率で判定。
  • MEDAL.parSpeed = 15.5 m/s を基準速度。
  • 閾値:
    • author ≤ 0.90 × par
    • gold ≤ 1.00 × par
    • silver ≤ 1.10 × par
    • bronze ≤ 1.25 × par
  • 判定は stageBests[seed].t と len から算出。
  • クリア時のリザルトと COLLECTION セルに表示。

5. 物理

5.1 車両モデル

自転車モデルを基礎に、荷重移動・スリップ角・タイヤ飽和・ヨー減衰を加えた 3 自由度(x, y, yaw)。

パラメータ値意味
m1100 kg車重
Iz1600 kg·m²ヨー慣性
lf / lr1.25 / 1.35 m前後輪までの距離
Cf / Cr40000 / 44000前後コーナリング剛性(低めで穏やかな飽和)
muF / muR1.45 / 1.75前後摩擦係数(リア高めで姿勢安定)
Pmax130 kW最高出力
FmaxEngine11000 N駆動力上限
FmaxBrake15000 N制動力上限
Cd1.05空気抵抗
Crr32転がり抵抗
maxSteer0.85 rad静止時切れ角
steerRate10.0 rad/s操舵速度
maxSteerHighSpeed0.40 rad高速時切れ角上限
speedSensV34 m/s舵角速度感度
yawDamp1000ヨー減衰
yawDampSlip0.7スリップ時の追加減衰
maxYawRate4.0 rad/sヨーレート上限

5.2 積分

  • 固定ステップ PHYS.dt = 1/120 s。
  • 1 フレームあたり最大 PHYS.maxSteps = 6 ステップ。
  • 残った時間はリセット(スパイラル防止)。

5.3 後退時

  • 前輪の実効舵角の符号を反転(revSign)。
  • 物理的に正しいヨー応答。

5.4 実装上の注意

  • 前輪スリップ角は vSafe = max(|vx|, 1.8) でゼロ除算を防ぐ。
  • isFinite チェックで NaN をゼロにリセット。
  • yawDampSlip は後輪スリップが 0.2 rad を超えると効き始め、0.8 rad で最大。

6. 路面サーフェス

3 段階。コース生成時に seed から基準面を抽選し、1 コース中に 2 ゾーン配置。

ID名前μ視覚
0concrete1.00紙のまま
1steel0.58青 rgba(55,110,205,0.55) + 青ハッチ
2grip1.50橙 rgba(235,120,30,0.52) + 橙ドット
  • 配置: seed で base 面を抽選 → セクション境界で 2 ゾーンを非重複配置。
  • 検出: updateCarSurface が最寄りの node の surf を返す。
  • 効果: SURFACES[car.surf].mu を gripMul に乗じて stepCar に渡す。
  • 視覚: μ と色を対応させ、直感的に「今どの面にいるか」が分かる。

7. HUD

7.1 レコードバー(上部)

項目ID内容
ブランド—RUBBING(朱)
BESTrb-bestTA のベストステージ番号(現状は未使用枠)
STAGErb-stage現在のステージ番号(1 始まり)
GATErb-gate通過数 / 総数
TIMErb-time経過秒(0.01 s 単位)
SEEDrb-seed#xxxxxxxx 16 進

7.2 中央メッセージ

  • カウントダウン、GO!、CLEAR、MISS、LOST、CLOSE。
  • クラス show / go / fail / clear で色分け。
  • <small> タグで補足テキスト。

7.3 セクターポップ

  • #sector-pop。S1 +0.42 形式。
  • ahead / behind クラスで色分け。
  • DELTA.popTime = 1.6 s 表示後に消える。

7.4 デルタバー

  • drawDeltaBar が canvas 上に描画。
  • 半透明のトラック + 中央目盛 + 塗り + 数値。

7.5 ドリフトスコア

  • スリップ角 > driftSlipMin かつ速度 > driftSpeedMin のとき加算。
  • 継続時間に応じて倍率(最大 3.0x)。
  • 画面右下に表示。

7.6 速度

  • 各ビューの左下に NNN KM/H。

8. テーマ:Paper Kit

8.1 方針

  • Neon は採用しない。発光は描かない。
  • 明るい紙の上に、Material Design 風の「物として置かれている」要素を描く。
  • 道路と背景は似た明るい色(クリーム紙 + 薄いタン)。
  • パイロン・車ははっきり描く(濃い色 + 影)。
  • タイヤの色変化(緑→黄→赤)は意味を持つので見えるように描く。
  • スキッド痕は面白さの要素として分かる程度に残す。

8.2 パレット

役割値意味
paper#f2ecdc生成り(背景)
ink#2a2018焦茶(本文)
accent#e85a32朱(次のゲート・アクセント)
gridrgba(140,120,90,*)薄茶(罫線)
road basergba(210,190,150,0.45)薄タン(路面)
steelrgba(55,110,205,*)青(滑る面)
griprgba(235,120,30,*)橙(食う面)
player#2a4a6a紺(自車)
rival#c8342a朱(ライバル)
pylon#2a4858濃紺(パイロン)
ghostrgba(100,140,180,*)青錆(ゴースト)
tireHSL 120°→0°緑→黄→赤(タイヤ負荷)

8.3 Material Elevation

setElevation(ctx, level) で統一された影を付ける:

levelshadowBlurshadowOffsetY用途
000影なし
12.50.8タイヤドット・小要素
251.6パイロン・車体

影の色は rgba(80,60,40, α)。α = 0.14 + level × 0.05。

8.4 描画規約

  • 発光を描かない(shadowBlur を光源として使わない。elevation 影のみ)
  • ベタ塗りをしない(紙にノイズを載せる、getPaperCanvas の ±5)
  • 直線を直線で描かない(微小に歪ませる)
  • 白を使いすぎない(地色は生成り)
  • 縁取りより面で見せる(Material の原則)

8.5 単位とスケール

  • 世界座標はメートル。
  • GAME.viewScalePx = 8.5 px/m(chase view)。
  • fit view は bounds に合わせて自動スケール。
  • 車体長 4.30 m、幅 1.80 m。
  • 道路半幅 2.8 m。

9. コース生成

9.1 ノードベース

  • 0.5 m 刻みのノード列(COURSE.nodeStep)。
  • セクションは直進・アーク・S 字・複合カーブからランダム選択。
  • 全長は 8〜16 セクション × 各セクション 8〜52 m。
  • 前後に 7 m / 9 m の直進を付加。

9.2 ゲート

  • COURSE.gateSpacing = 32 m 間隔。
  • 初回は 18 m 地点(firstGate)。
  • 幅は gateHalfMin 〜 gateHalfMax = 2.0 〜 3.8 m。
  • 難度 dif = clamp01(stageIndex/12) で幅を狭める。
  • パイロンと干渉する場合は外側へ押し出す(pylonExtendStep 0.4 m、最大 10 m)。

9.3 パイロン

  • 各ゲートの両端に配置。
  • pylonR = 0.30 m、安全マージン pylonSafeMargin = 0.6 m。
  • コースから離れた位置に押し出して配置。

9.4 サーフェスゾーン

  • 基準面 = rng.int(0, 2) で抽選。
  • ゾーン長 2〜4 セクション、非重複で 2 ゾーン。
  • 隣接ゾーンは同じ面にならない。
  • ゾーン外は基準面。

9.5 曲率

  • 各ノードで前後の中点からの角度差 / 距離 = 曲率。
  • Bot の速度目標計算に使用。

10. Bot

10.1 追従

  • 最寄りノードから前方 Ld = clamp(v * lookTime, 5, 16) m を目標点とする。
  • 目標点への角度誤差 × steerKp − ヨーレート × steerKd で操舵。
  • 前方 50 ノードの最大曲率から vTarget = clamp(sqrt(aLat / maxK), 6, vTop)。

10.2 スキル

  • botParamsForStage(stageIndex, skill) で aLat, vTop, gripMul, lookTime を補間。
  • skill は BOT.skillBase = 0.35 から BOT.skillMax = 1.00 へステージごとに上昇。
  • gripMul は最大 1.08(人間より少し食う)。

10.3 制限

  • Bot はパイロンを避けない(コース中央を走る前提)。
  • Bot は手放しでもコース上を走る(学習対象ではない)。

11. アーキテクチャ

11.1 ファイル構成

public/tools/rubbing/ 配下:

manifest.json
index.html テンプレート
styles/
10-base.css
20-hud.css
30-controls.css
40-menu.css
js/
10-math.js clamp, lerp, wrapAngle, dist, ...
20-rng.js hashSeed, createRng (xorshift)
30-config.js すべての定数 + COLORS
40-storage.js localStorage, ghost encode/decode
50-input.js タッチ・キーボード入力, ステアリング UI
60-physics.js 車両物理 stepCar
70-course.js コース生成, ゲート/パイロン判定
80-ghost.js ゴーストのエンコード/デコード/再生
90-bot.js Bot の追従ロジック
95-camera.js chase / fit カメラ変換
100-render.js canvas 描画全般
110-hud.js DOM HUD 更新
115-collection.js シードコレクション画面
120-game.js ゲーム状態機械, updateGame
130-boot.js entry point, boot()
bundle/
index.html 生成物
tmp/ verify の一時領域

11.2 依存方向

10-math ────┐
20-rng ─────┤
30-config ──┤
▼
40-storage 50-input 60-physics 95-camera
│ │
▼ ▼
80-ghost 70-course 90-bot
│
▼
100-render 110-hud 115-collection
│
▼
120-game
│
▼
130-boot

循環依存なし。bundle.mjs の topo sort が決定論的な順序を生む。

11.3 directive / import / export

2026-09-28-html-split-bundle-規約 に従う。

  • 各ファイル先頭に // === @file: js/NN-name.js ===
  • 2 行目以降に // @import: と // @export:
  • directive と実 import / export は 1:1 対応
  • すべての const / function に export を付ける(@export: に列挙されたもの)

12. データ永続化

12.1 localStorage キー

キー内容
gk:profile:v2プロファイル(version 3 に自動移行)
gk:ghost:v3:{seed}ゴースト配列(最大 3 本、新しい順)
gk:defeat:v3:{seed}敗北ゴースト(1 本)

12.2 プロファイル

{
version: 3,
stageBests: {
"{seed}": { t: number, at: number, len: number }
},
seedOrder: number[], // 発見順
battleBestStage: number
}

12.3 ゴーストエンコード

各サンプル 8 byte:

オフセット型内容
0Int16x × 100 (cm)
2Int16y × 100 (cm)
4Int16ang × 1000 (mrad)
6Uint8gates 通過数
7Uint8予約

base64 エンコードして保存。30 Hz × 60 s = 1800 サンプル = 14.4 KB。


13. 入力

13.1 タッチ

操作ゾーン挙動
ステア画面左下 1/2 × 下 20%押下点を中心に左右ドラッグ
アクセル画面右下 1/2 × 下 20%押下点から上ドラッグ
ブレーキ同上押下点から下ドラッグ
ハンドブレーキ右下 46×46 px押下中アクティブ
  • CTRL.steerRangePx = 60 / pedalRangePx = 70。
  • ステアは非線形(steerExp = 1.30)。
  • ゾーン端で原点をクランプ(範囲外に出ない)。

13.2 キーボード

キー動作
← / →ステア
↑ / ↓アクセル / ブレーキ
Spaceハンドブレーキ

13.3 入力状態

{
steer: -1..1,
throttle: 0..1,
brake: 0..1,
handbrake: bool,
keys: { left, right, up, down, hb }
}

resetInput で各走行開始時にゼロ化。


14. カメラ

14.1 chase view

  • 自車の前方 lookAhead m を中心に、進行方向を上に回転。
  • 車体は画面下半分に配置。
  • 速度に応じて lookAhead と scale を微調整(速度感の演出)。

14.2 fit view

  • TA の上部に表示。コース全体を bounds + pad でフィット。
  • 自車位置にドットを描画。

14.3 レイアウト

[ recordbar 36px ]
[ topRect viewH * 0.42 ]
[ botRect viewH * 0.58 ]
[ controls ctrlH ]

ctrlH = min(h * 0.20, 150)。


15. 未実装 / 今後の候補

  • 上位 3 ゴーストの選択 UI(データは既に保持)
  • 敗北ゴーストの視覚差別化(青錆 vs 淡茶)
  • リプレイスクラブ(任意ゲートから再開)
  • デイリーシード(日付ハッシュ、オフライン可)
  • セクター区切りのコース上の視覚マーカー
  • 連勝記録の保存と表示
  • ニアイメージ「COURAGE」ボーナス(タイム非干渉の演出)
  • ゴーストの頭出し(0.3s 遅延)

16. ビルド・検証

16.1 通常の開発

Terminal window
# ソースを編集
node scripts/html-build/audit-imports.mjs --project rubbing
node scripts/html-build/bundle.mjs --project rubbing
node scripts/html-build/verify.mjs --project rubbing

3 コマンドすべて exit 0 が条件。

16.2 単一 HTML からソースへ

Terminal window
node scripts/html-build/split.mjs --project rubbing --in bundle/index.html --out .

index.html は dev 形式(<link> + <script src>)に書き換わる。

16.3 検証

  • verify: bundle → split → 比較。全一致で exit 0。
  • audit-imports: directive ↔ 実 import/export の不整合検出。[missing] は手動修正。

17. 数値一覧(調整ポイント)

物理・ゲームバランスの主要数値。実プレイで調整する場合の早見表。

症状調整
まだ曲がらないCAR.maxYawRate ↑, CAR.yawDamp ↓
スピンしすぎCAR.muR ↑, CAR.Cr ↓, CAR.yawDampSlip ↑
加速で失速CAR.FmaxEngine ↑, CAR.muR ↑
唐突に滑るCAR.Cf/CAR.Cr ↓, CAR.yawDampSlip ↑
路面差が弱いSURFACES[i].mu の差を拡大
Bot が強すぎBOT.skillBase ↓, BOT.aLatSpan ↓
メダルが取りにくいMEDAL.parSpeed ↑

すべて export されているので、devtools から CAR.maxSteer = 1.0 のように上書きして試せる。


18. 用語

用語意味
seedコース生成の種。16 進 8 桁で表示
gate通過すべき門。コース上 32 m 間隔
pylonゲート両端の障害物。接触で MISS
splitセクター通過タイム
deltaベストゴーストとの時刻差
ghost過去の自分の走行記録
parコース全長から推定した基準タイム
skillBot の強さ(0.35 〜 1.00)
elevationMaterial Design 風の影の段階

19. 関連ドキュメント

  • 2026-09-28-html-split-bundle-規約 — 分割ソースと単一 HTML の相互変換ルール
  • 2026-09-27-text-chunker-spec — 同じ規約を使う別プロジェクト