Communitygithub.com

evalix098/tiktoklive

適用於瀏覽器遊戲的玩家面向輸入標誌:WASD、載具、飛行、FPS 滑鼠視角,以及最常見的失敗模式(反向 A/D)。包含強制性控制自我測試和一個小型測試介面,讓您能在發布前確認 A 鍵是左轉。適用於任何具有移動、轉向、飛行、駕駛、坦克、船隻、機甲、無人機、飛機、卡丁車、第三人稱跟隨攝影機的遊戲 — 不限於競速類。觸發關鍵字:「controls」、「WASD」、「inverted」、「steer」、「flight」、「airplane」、「kart」、「vehicle」、「yaw」、「roll」、「pitch」、「mouse look」、「A/D」。

tiktoklive 是什麼?

此技能旨在解決瀏覽器遊戲開發中最常見且最令人沮喪的錯誤之一:反向 A/D 控制。它提供了一套嚴格的規則、數學基礎和程式碼範例,確保 WASD 和方向鍵的輸入在玩家的視角中始終正確—即 A 或左箭頭應讓螢幕上的物體向左轉,而 D 或右箭頭則向右轉。技能涵蓋了多種遊戲類型,包括 FPS 第一人稱射擊、地面與水上載具、固定翼飛行、直升機/無人機以及 2D 橫向卷軸平台遊戲,並針對每一種類型提供了具體的輸入映射和整合邏輯。它強烈要求開發者在完成之前必須執行一個「控制自我測試」,透過一個小型測試介面來驗證方向正確性,而非僅依賴螢幕截圖。此技能支援任何需要移動、轉向或飛行的遊戲,並可與其他建構遊戲的技能和輸入參考文件搭配使用,是確保玩家體驗一致且無錯誤的關鍵資源。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/evalix098/tiktoklive/tree/HEAD/.grok/skills/controls

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

控制(玩家可見標記 — 切勿使用反向設定)

在為任何使用 WASD、方向鍵、追蹤攝影機或飛行載具的遊戲撰寫移動/操控/飛行程式碼之前,請完整閱讀此內容。 請不要跳過這部分而只查看 racing-kart 或 fps —— 那些類型檔案假設你已經知道這些標記。A/D 反向是車輛和飛行示範中最常見的阻礙因素。

請搭配 building-games(迴圈、攝影機、3D 方向)和 building-games/references/input.md(按鍵按下狀態、遊戲手把、觸控)一起使用。這個技能文件定義了左/右/上對玩家而言的意義以及你如何證明它。


0. 硬性規則(違反則建置失敗)

  1. 玩家可見的左/右是鐵律。 從追蹤 / 後方攝影機視角,並且載具向前移動時:
    • A / ← → 機頭(或傾斜)在螢幕上向左轉
    • D / → → 機頭(或傾斜)在螢幕上向右轉
  2. 絕對不要將 FPS 的橫向移動當作車輛操控。 FPS 的「D → +右向量」是地面平面上的位置位移。車輛的 A/D 是偏航(或滾轉)速率,而不是橫向偏移。將兩者混用是造成 A/D 反向的第一大原因。
  3. 在說完成之前,你必須執行控制自我測試(§5)。 僅截圖驗證是不夠的。如果 A 讓載具向右轉,請翻轉操控/滾轉的正負號,重新測試,然後出貨 —— 不要發明一個新的座標故事。

1. 共享的 3D 基礎(請於各處使用此設定)

three.js:右手坐標系,+Y 朝上,網格面向 +Z,攝影機看向 −Z。

僅偏航的 XZ 平面航向(地面車輛、步行機、大多數街機風格載具):

// yaw = 0 時朝世界 −Z 方向;+yaw 繞 +Y 軸逆時針旋轉(機頭朝 −X 方向移動)
forward = (-sin(yaw), 0, -cos(yaw))
right   = ( cos(yaw), 0, -sin(yaw))   // = normalize(cross(forward, worldUp))

使用後方追蹤攝影機時(攝影機位置接近 position - forward * dist):

玩家所見世界(此基礎)輸入
機頭向左+yawA / ← 必須產生 +yaw(或飛機的等效向左傾斜)
機頭向右−yawD / → 必須產生 −yaw

如果你的基礎不同,請保持一組一致的正負號 —— 但你必須強制遵守上表中玩家所見那一行的規定。


2. 類型對應

2a. FPS / 步行(橫向移動,非操控)

W = +前進, S = -前進, D = +右, A = -右   // 位置,非偏航
滑鼠:yaw -= movementX * sens; pitch -= movementY * sens; 限制 pitch 範圍

身體偏航用於觀看方向;移動只使用偏航(不要對步行應用 pitch)。

2b. 地面 / 水上車輛(卡丁車、腳踏車、水上摩托車、船、坦克、探測車、雪地摩托車)

使用 heading/yaw 和前進 speed 的街機風格主體:

// 輸入(按住按鍵 → 每幀執行一次動作)
let steer = 0; // -1..+1,玩家可見
if (keys.has('KeyA') || keys.has('ArrowLeft'))  steer += 1;  // 左
if (keys.has('KeyD') || keys.has('ArrowRight')) steer -= 1;  // 右
// 可選:steer = clamp(steer + gamepadX, -1, 1) 使用相同正負號慣例

// 積分(speedFactor ~ 0..1 來自 |speed|)
const reverse = speed >= 0 ? 1 : -1; // 倒車時左轉仍然感覺像左轉
yaw += steer * turnRate * speedFactor * reverse * dt;

// 沿航向移動
const fx = -Math.sin(yaw), fz = -Math.cos(yaw);
position.x += fx * speed * dt;
position.z += fz * speed * dt;

典型錯誤(請勿複製):

// 錯誤 —— 這就是實際開發中造成 A/D 反向的原因
if (KeyA) steer -= 1;
if (KeyD) steer += 1;
yaw += steer * turnRate * dt;  // A → -yaw → 追蹤攝影機視角下機頭向右

如果你已經寫了 KeyA → steer--,請交換按鍵對應或在積分時取一次負值(yaw += -steer * …)—— 然後執行 §5。不要翻轉兩次(按鍵 + 積分 + 網格傾斜)。

2c. 固定翼飛行(飛機、滑翔機、遙控飛機)

輸入動作玩家預期
A / ←向左滾轉(副翼)左翼向下 / 向左傾斜
D / →向右滾轉右翼向下 / 向右傾斜
W / ↑俯仰(選擇一種方案並在 HUD 上標示)通常是機頭向下 或 拉機頭向上 —— 需保持一致
S / ↓相反俯仰
Q / E偏航 / 方向舵(可選)Q 左轉,E 右轉
  • A/D 不是橫向移動,也不是「使用 FPS 正負號的地面操控」。
  • 在載具的局部前進軸上應用滾轉,其正負號需與 按 A 向左傾斜 相符。如果網格傾斜方向錯誤,請翻轉一個正負號(在滾轉應用或 A/D 到滾轉的對應上),而不是翻轉整個基礎。
  • 協調轉彎:在追蹤/外部攝影機下,正的傾斜應產生與傾斜方向相符的轉彎。

2d. 直升機 / 無人機 / 六自由度飛行器

請在開始疊層中記錄控制方案。至少需包含:

  • 油門/高度的離散按鍵在按一次後不應保持「永遠上升」的狀態(使用按住狀態或明確的向上/向下)。
  • 橫向移動/偏航:A 左轉,D 右轉,在載具的水平框架中(玩家可見)。

2e. 2D 橫向捲軸 / 平台遊戲

D / → 在螢幕上向右移動;A / ← 向左移動。除非遊戲類型明確是上下顛倒,否則重力不應反向。


3. 攝影機必須一致

  • 追蹤攝影機:desired = craftPos + up*height + forward*(-followDist);插值;lookAt(craft)。
  • 一次計算 forward 用於移動和攝影機 —— 不要在攝影機路徑中使用相反的偏航正負號重新計算。
  • 除錯順序:(1) 按鍵註冊 → (2) 正負號正確(§5)→ (3) 攝影機一致。

4. 輸入管道(簡要說明)

  • 使用 Set 在 keydown/keyup 事件中追蹤按鍵,使用 event.code;在 blur / visibilitychange 時清除。在遊戲迴圈中使用 dt 移動,而不是在按鍵處理函數中。
  • 將鍵盤 + 觸控 + 遊戲手把統一成動作(throttle、steer、pitch、roll、…)。請參閱 building-games/references/input.md。
  • 觸控:左搖桿 = 移動/操控,右搖桿 = 動作;按鈕目標大小 ≥44px。

5. 強制性控制自我測試(在說「完成」之前)

對於任何使用 A/D 的載具,僅截圖不足以驗證。

5a. 玩家可見檢查清單(每個車輛 / 飛行建置)

當向前移動(速度 > 小正數 epsilon)時,追蹤攝影機在後方:

按住必須在約 0.5 秒內觀察到
A機頭或傾斜在螢幕上向左移動
D機頭或傾斜在螢幕上向右移動
W(地面)速度增加 / 沿面對方向移動
S(地面)煞車或倒車(依設計)

如果 A 測試失敗:翻轉操控/滾轉正負號一次,重新測試 A 和 D。

5b. 最小測試介面(實作此介面)

暴露一個小的鉤子,讓你和自動化 QA 可以在不猜測私有閉包的情況下證明正負號:

// 例如 src/game/controlsTest.ts —— 僅限開發/QA 即可
export type ControlsProbe = {
  getYaw: () => number;       // 弧度;或 getHeading()
  getSpeed: () => number;
  /** 注入按住的動作而非真實按鍵;兩者都會保持直到你改變它們,
   *  因此 §5c 可以在多幀中按住一個按鍵並在最後清除。 */
  setSteer?: (v: number) => void; // -1..1,與生產程式碼相同正負號
  setKeys?: (codes: string[]) => void; // 保持按住直到下一次呼叫;`[]` 清除
};

declare global {
  interface Window {
    __controlsTest?: ControlsProbe;
  }
}

當 import.meta.env.DEV 或設定 ?qa=1 旗標時,從遊戲迴圈中連接 window.__controlsTest。

5c. 自動化冒煙測試(執行它)

使用預先安裝的 agent-browser CLI 驅動 §5b 的探針 —— 這是第一步,而不是手寫腳本。拋出的 eval 會以非零退出;僅僅是假值則不會,因此請透過拋出錯誤來斷言。作為一個 batch 執行 —— 一次 CLI 呼叫,而不是每個動作一次 —— 在 stdin 接收 JSON;--bail 在第一個失敗的步驟時停止並以非零退出。

agent-browser batch --bail <<'JSON'   # find 的 label 區分大小寫:從 `snapshot -i` 複製
[["open","http://127.0.0.1:8080/"],
 ["find","text","Start","click"],
 ["eval","if (!window.__controlsTest?.setKeys) throw Error('no §5b probe: add setKeys')"],
 ["eval","__controlsTest.setKeys(['KeyW'])"],
 ["wait","600"],
 ["eval","if (__controlsTest.getSpeed() <= 0.1) throw Error('W: no move')"],
 ["eval","(async () => { const t = __controlsTest, y0 = t.getYaw(); t.setKeys(['KeyW','KeyA']); await new Promise(r => setTimeout(r, 300)); t.setKeys(['KeyW']); const d = t.getYaw() - y0, w = Math.atan2(Math.sin(d), Math.cos(d)); if (w < -0.05) throw Error('A turns RIGHT — inverted, got ' + w.toFixed(2)); if (w <= 0.05) throw Error('A barely turned (' + w.toFixed(2) + ') — hold longer or check the sim is running'); return 'A ok' })()"],
 ["eval","__controlsTest.setKeys([])"],
 ["screenshot","/workspace/screenshots/controls.png"],
 ["close"]]
JSON

透過探針按住按鍵,而不是使用 keydown —— agent-browser keydown 無法到達 §4 的 Set,因此正確的遊戲會顯示為有問題。你的探針沒有 setKeys?新增它(§5b),或者自己派發按鍵事件 —— 瀏覽器 QA 參考文檔的 Keys 說明中包含了機制和形式。

按住動作位於一個 eval 內部:分散在多個命令中時,其持續時間取決於每個命令所花時間,並且 Math.atan2(Math.sin(d), Math.cos(d)) 中的 ±π 包裹會將轉彎超過 π 的載具解讀為轉向另一邊。IIFE 是讓步驟可以重複執行的關鍵 —— 普通的 const d = … 在第二次執行時會因「已宣告」而失敗 —— 而 async 則讓按住可以在頁面時間內執行。對 D 重複此測試,使用 'KeyD' 並將兩個比較鏡像(w > 0.05 是反向,w >= -0.05 是不足),使用單引號以便 JSON 不需要跳脫;對於飛機,斷言 roll:A ⇒ 向左傾斜。

A turns RIGHT 是正負號錯誤:翻轉一個正負號並重新執行。 A barely turned 不是錯誤 —— 載具移動方向正確,只是在 300 毫秒內移動了不到 0.05 弧度,這對於船或重型探測車來說是正常的;請延長按住時間,或檢查模擬是否正在運行,無需翻轉任何東西。任何其他非零退出 —— 沒有探針、守護行程卡住 —— 表示檢查從未執行:請先閱讀訊息。在開始你的第一個流程之前,請閱讀瀏覽器 QA 參考文檔 AGENTS.md 中的連結 —— 動詞、參數形狀和備用方案都在那裡。

5d. 不要做的事

  • 不要只測試「D 增加了某個內部變數」。
  • 不要將 FPS 的「D → +X 當面向 -Z 方向」當作車輛測試通過的條件。
  • 不要在修復時同時翻轉網格傾斜、攝影機和操控 —— 一次只改變一個正負號,然後重新測試。

6. 完成條件(控制)

  • 在編寫移動/操控/飛行程式碼之前已開啟此技能文件。
  • 已選擇類型對應(§2)且開始畫面 / HUD 標籤與之相符。
  • 追蹤攝影機 A/D 玩家可見測試通過(§5a)。
  • 在開發/QA 環境中提供 window.__controlsTest(或等效功能)並已使用一次。
  • 相對於滾轉/操控輸入,沒有反向傾斜的網格。
  • 按鍵是按住狀態 + dt 縮放;沒有因為單次按下空格鍵而卡住推力,除非是有意為之且有標示。

如果有任何一個方框未勾選,表示遊戲尚未完成。

Individual skills in this repo

This repo contains 17 individual skills — each has its own dedicated page.

evalix098/tiktoklive

Add user accounts and sign-in to this TanStack Start app. Use when the app needs authentication, sign-in, user accounts, protected routes, or per-user data. Triggers on "auth", "login", "log in", "sign in", "sign up", "account", "users", "authentication", "protected", "who is logged in", "current user", "per-user".

evalix098/tiktoklive

Build browser games and interactive/canvas/3D experiences in this TanStack Start + React app. Use for any game, simulation, or WebGL/Canvas experience — 2D or 3D, single-player. Covers the game loop & timing, 3D orientation/camera conventions, collision, performance, assets, audio, save, game feel, and per-genre playbooks. For WASD / vehicle / flight **input signs and inverted A/D**, open the **`controls`** skill — do not rely on this file or racing-kart alone. Triggers on "game", "minecraft", "fps", "platformer", "racing", "tetris", "snake", "shooter", "3d", "three.js", "canvas", "voxel", "physics".

evalix098/tiktoklive

Design and build polished, non-generic UI for this TanStack Start + React + Tailwind v4 + shadcn/Radix app. Use whenever you create or restyle any interface surface — pages, landing pages, dashboards, forms, modals, nav, and game overlays (start screens, HUD, menus). Covers design tokens, layout, typography, color, spacing, motion, and the anti-"AI-slop" rules that keep output from looking generic. Triggers on "design", "UI", "make it look good", "polish", "landing page", "theme", "style", "redesign", "ugly", "clean up".

evalix098/tiktoklive

Deep guide for game ANIMATION assets: motion cycles, action keyframes, effect sequences, and animation sprite sheets — built around a video-first pipeline. In this app-builder sandbox, execute via the video2dsprite / generate2dsprite skills (magenta + scripts), not ad-hoc ffmpeg. Use whenever generating anything that moves: walk/run cycles, attacks, idles, FX, flags, fire, animation sheets. Complements game-asset-core.

evalix098/tiktoklive

Core discipline for ANY game-asset generation with Imagine tools: the engine-ready defaults users don't state, spec checklists, style anchoring, read-back verification, honest defect flagging. Use whenever generating any game art (sprites, sheets, animations, tiles, UI, FX) — then ALSO load the matching specialist skill: game-animation-frames for anything that moves, game-tilesets for tiles/terrain, game-character-consistency for recurring characters, game-ui-icons for UI and icons.

evalix098/tiktoklive

Deep guide for CHARACTER IDENTITY across images: turnarounds (front/side/ back), state and damage variants, palette swaps, equipment changes, and same-character-in-context sets. Use whenever generating character turnarounds, character sheets, variants of an existing sprite, or any same-subject multi-image set. Complements game-asset-core.

evalix098/tiktoklive

Deep guide for game TILE assets: seamless tileable textures, terrain transition tilesets, autotiles, and ground/platform tiles. Use whenever generating tileable textures, tilesets, terrain transitions, or seamless patterns. Complements game-asset-core.

evalix098/tiktoklive

Deep guide for game UI assets: buttons with interaction states, panels, bars, wordmark logos, and icon sets. Use whenever generating game UI elements, HUD assets, inventory icons, icon sets, buttons, or title logos. Complements game-asset-core.

evalix098/tiktoklive

Generate production-oriented 2D game maps with `imagine_text_to_image`: RPG/top-down maps, side-scroller parallax stages, tilemaps, layered raster maps, prop packs, collision zones, and walkable areas. Use when building browser games that need real map art (not pure code-drawn tiles), layered props, or map collision metadata. Triggers on "map", "level", "stage", "tilemap", "overworld", "dungeon", "side scroller background", "prop pack", "2D map".

evalix098/tiktoklive

Generate and postprocess 2D game sprites and animation sheets: pixel-art characters, NPCs, creatures, spells, projectiles, impacts, props, summons, and transparent PNG/GIF exports. Use when building browser games that need real sprite sheets (not code-drawn placeholders), matching a map art style, or producing magenta-background sheets for chroma-key cleanup. Triggers on "sprite", "sprite sheet", "animation sheet", "pixel art character", "walk cycle", "attack animation", "projectile sprite", "2D game asset".

evalix098/tiktoklive

How to use the Imagine tools in Grok Build: imagine_text_to_image, imagine_image_to_image, imagine_reference_to_image, imagine_text_to_video, imagine_image_to_video, imagine_reference_to_video, and render_file for chat previews. When to build a visual with code instead of generating it, prompt-craft, reference-first handling of real people, factual grounding, and asset-consistency. Load this whenever generating or editing an image or video is on the table. Tool-usage-driven, not triggered by a user merely mentioning images.

evalix098/tiktoklive

Peer-to-peer realtime multiplayer over WebRTC data channels: every user of the deployed app connects directly to every other user (full mesh), the server only brokers the handshake at /api/rtc. Lowest possible latency, zero per-message server cost. Use for 2-8 player co-op/casual realtime: shared cursors, drawing, party games, casual action. Triggers: p2p, peer to peer, webrtc, low latency multiplayer, direct connection.

evalix098/tiktoklive

Use Neon Postgres (the database) in this TanStack Start app. Use when the app needs to store or query data, persist state, or keep per-user data. Triggers on "database", "Postgres", "Neon", "save data", "store data", "persist", "tables", "SQL", "query", "migrations".

evalix098/tiktoklive

Share-link previews and app identity for apps on *.grok.me: the injector-owned og:image card, the SVG favicon, and PWA icons for installable apps. Use when scaffolding, renaming, or restyling the app — and for share / unfurl / OG / Twitter card questions. A custom 1200×630 card from the app's own art is the default — games of every kind (DOM board/word games included), whimsical apps, creative tools, and brand-forward pages; only plain utilities keep the placeholder. Always run the brand-asset pass as a `task` subagent and never wait for it. Triggers on "share", "rename", "app name", "OG", "Open Graph", "twitter card", "unfurl", "og:image", "og:type", "x:game:image", "x-banner", "link preview", "social card", "thumbnail", "preview image", "favicon", "app icon", "PWA", "manifest", "installable", "home screen", "SEO", "meta description".

evalix098/tiktoklive

Official Three.js API and TSL (Three.js Shading Language) reference for LLM code generation. Load when writing or debugging three.js / WebGL / WebGPU / custom materials / shaders / GLTF / advanced three APIs beyond basic game loop/controls. Prefer building-games for game correctness (loop, WASD, camera, orientation); use this skill for full API/TSL depth. Triggers on "three.js", "threejs", "WebGPU", "TSL", "NodeMaterial", "shader", "GLTF", "MeshStandard", "OrbitControls", "WebGLRenderer".

evalix098/tiktoklive

Grok Build only. Turn a 2D character still into denser animation sprites via imagine_text_to_image base → imagine_image_to_video (6s/10s run-in-place) → ffmpeg frames → magenta chroma-key → dense sampled strips/grids/GIFs. Use when the user wants video-to-sprite, smoother run/walk cycles, or denser intermediate poses. Prefer generate2dsprite for crisp production pixel sheets. Triggers on "video to sprite", "imagine_image_to_video sprite", "dense walk cycle", "smooth run animation from video".

evalix098/tiktoklive

Call the xAI API (Grok) from this app's server code using the injected XAI_API_KEY: chat/LLM features, image and video generation (Imagine), and voice (text-to-speech). Use when the app needs any "AI" / "assistant" / "chatbot" / "Grok" functionality, runtime image/video generation, or speech. Triggers on "AI", "LLM", "chatbot", "assistant", "Grok", "xAI", "generate text", "summarize", "generate image", "AI video", "voice", "text to speech", "TTS", "OpenAI" (use xAI instead).

相關技能