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 是什么?

该技能为浏览器游戏(如使用 WASD、箭头键、追尾摄像头或飞行载具的游戏)提供了明确的面向玩家的控制标记方案,其核心是防止最常见的错误——反向 A/D 控制(即按 A 向右转,按 D 向左转)。它通过详细的 3D 数学基础(基于 three.js 右手系,+Y 向上)、针对不同流派(FPS、地面/水上载具、固定翼飞行、直升/无人机、2D 横版)的输入映射规则,以及强制性的“控制自检”流程来确保方向正确。技能强调,从追尾视角看时,按 A 或左箭头必须使机头或侧倾向左转,按 D 或右箭头必须向右转;严禁将 FPS 的瞄准平移(strafe)混用为载具转向。该技能提供了完整的 JavaScript 参考实现、调试用暴露接口(`window.__controlsTest`)以及可直接运行的 `agent-browser` 自动化烟雾测试脚本,要求在人眼确认前必须执行自检。它支持 Claude Code、Cursor、Codex 等 AI 代理工具,也能作为任何 Web 游戏控制逻辑的权威规范。

兼容平台~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 平移(strafe)复用作载具转向。 FPS 中 "D → +right vector" 是地面平面上的位置移动。载具的 A/D 是偏航(或滚转)速率,而非平移偏移。将它们混用是导致 A/D 反向的头号原因。
  3. 在说完成之前,你必须运行控制自检(§5)。 仅凭截图 QA 是不够的。如果按 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 = +forward, S = −forward, D = +right, A = −right   // 位置移动,而非偏航
鼠标:yaw -= movementX * sens; pitch -= movementY * sens; 限制 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. 直升机 / 无人机 / 六自由度(6DOF)

在开始覆盖层上记录方案。最低要求:

  • 离散按键上的油门/高度不得在按一次后“始终向上”(使用按住状态或明确的上下键)。
  • 平移/偏航:在载具的水平框架内,A 向左,D 向右(面向玩家)。

2e. 2D 横版卷轴 / 平台游戏

D / → 在屏幕上向右移动;A / ← 向左移动。仅在游戏流派明确为上下颠倒时才反转重力。


3. 摄像机必须保持一致

  • 追尾摄像机:desired = craftPos + up*height + forward*(-followDist);插值;lookAt(craft)。
  • 一次计算 forward 并同时用于移动和摄像机——不要在摄像机路径中使用相反的偏航符号重新构建。
  • 调试顺序:(1) 按键注册 → (2) 符号正确(§5)→ (3) 摄像机保持一致。

4. 输入管道(简要说明)

  • 使用 event.code 在 keydown / keyup 事件上用 Set 追踪按键;在 blur / visibilitychange 上清除。在游戏循环中使用 dt 进行移动,而不是在按键处理器中。
  • 将键盘 + 触摸 + 手柄统一为动作(throttle、steer、pitch、roll……)。请参阅 building-games/references/input.md。
  • 触摸:左摇杆 = 移动/转向,右摇杆 = 动作;目标区域 ≥ 44px。

5. 强制控制自检(在“完成”之前)

对于任何使用 A/D 的载具,仅凭截图是绝对不够的。

5a. 面向玩家的检查清单(每个载具 / 飞行构建)

在向前移动时(速度 > 小阈值),追尾摄像机位于后方:

按住必须在约 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 以非零退出;仅 falsy 值不会,因此通过抛出进行断言。将其作为一次 batch 运行——一次 CLI 调用,而不是每个动词一次——从标准输入读取 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)。
  • window.__controlsTest(或等效方法)在开发/QA 中可用并被使用。
  • 相对于滚转/转向输入,没有反向的侧倾网格。
  • 按键是按住状态 + 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).

相关技能