Communitygithub.com

evalix098/tiktoklive

在此TanStack Start + React应用中构建浏览器游戏及交互式/Canvas/3D体验,适用于任何游戏、模拟或WebGL/Canvas项目——2D或3D、单人模式。涵盖游戏循环与计时、3D方向/摄像机约定、碰撞、性能、资源、音频、保存、游戏手感及各类别剧本。

tiktoklive 是什么?

该技能专为在React应用中开发可玩、正确的浏览器游戏而设计,为游戏循环、3D方向、摄像机对齐和性能优化提供全面的框架和约定。它确保所有移动都按增量时间缩放以实现帧率无关性,建议使用`THREE.Timer`而非`Clock`以避免常见冻结bug,并强制物理模拟使用固定时间步长以保持确定性。对于输入处理,该技能将WASD、转向和飞行控制委托给专用的`controls`技能,以防止常见的反转A/D错误,并在3D网格方向方面提供详细指导,避免“朝向错误”的bug。该技能支持多种平台,包括独立游戏、AI机器人游戏以及使用WebRTC网络的2至8人P2P合作游戏,同时为资源生成和维护规定了严格原则,例如使用真正的3D几何体/glTF而非平面生成图像。它引用了一系列专业文档,涉及Three.js、Phaser、Babylon.js、ECS架构、游戏手感、碰撞物理和程序化生成,并包含一份明确的完成标准清单,以确保无控制台错误的发布、正确的输入行为以及移动端触摸控制支持。

兼容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/evalix098/tiktoklive/tree/HEAD/.grok/skills/building-games

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

构建游戏

构建一个可玩、正确的浏览器游戏——不是静态截图。游戏只是React路由中的一个<canvas>(或R3F的<Canvas>)加上DOM叠加UI。使用**design-ui**技能设计叠加界面(开始界面、HUD、菜单);本技能负责游戏循环和世界。

控制 / 反转A/D: 在编写WASD、转向或飞行输入之前,请打开**.grok/skills/controls/SKILL.md**。如果只阅读本文件或单个类型剧本,车辆/飞行演示通常会出现A/D反转的问题。

范围说明——单人、机器人或小型P2P合作:

  • 默认发布单人或单人+AI/机器人。
  • 支持2–8人合作/休闲实时(共享光标、派对游戏、朋友间的休闲动作)——使用**multiplayer-p2p技能**(WebRTC网状网络,通过/api/rtc信令)。请先阅读其信任模型。
  • P2P是目前唯一支持的多玩家方式。不要半途而废地构建无法连接的套接字。

参考资料(按需加载):

  • controls技能(../controls/)——必需用于移动/转向/飞行:玩家可感知的A/D、反转转向反模式、飞行副翼、强制性自检 + window.__controlsTest。对于车辆/飞行器并非可选。
  • references/threejs-foundational.md——深入的3D/循环/性能参考。用于3D阅读。
  • references/3d-libs.md——three.js + @react-three/fiber + drei + rapier 使用方式。
  • threejs技能(../threejs/)——官方完整Three.js + TSL API转储(llms-full.txt)。用于高级材质/着色器/WebGPU/加载器;不用于简单的2D Canvas游戏。
  • references/babylon.md——Babylon.js,功能完备的3D引擎替代品。
  • references/phaser.md——Phaser 3,默认的2D游戏引擎。
  • references/ecs-architecture.md——适用于大型游戏的实体组件系统结构。
  • references/genres/*.md——各类别剧本(FPS、2D平台跳跃、赛车卡丁车、益智三消俄罗斯方块、体素我的世界、无尽跑酷、俯视角双摇杆、塔防、棋盘卡牌象棋)。类型文件不能替代**controls**。
  • references/game-feel-juice.md、input.md、audio.md、collision-physics.md、save-persistence.md、procedural-generation.md、ai-pathfinding.md。
  • game-asset-core(+ game-animation-frames / game-tilesets / game-character-consistency / game-ui-icons)——在生成精灵、图集、图块或UI时,提供引擎就绪的2D美术默认值和验证(参见§6)。

为构建选择特定的类型/主题参考;本文件是循环/世界的通用核心。输入符号→controls。 2D游戏美术→game-asset-core。


1. 游戏循环与计时(#1正确性问题)

  • 使用引擎的RAF循环驱动循环(renderer.setAnimationLoop、R3F的useFrame或2D Canvas的requestAnimationFrame)。绝对不要使用setInterval/setTimeout/Date.now()进行游戏计时。
  • 根据增量时间(秒)缩放所有移动/动画,使速度与帧率无关(60Hz与144Hz)。每帧计算一次增量并重复使用。
    • three.js:使用THREE.Timer(而非Clock——在同一个帧内第二次调用Clock.getDelta()会返回约0,这是一个经典的冻结bug)。
  • 限制增量上限(min(delta, 0.1)),防止后台标签页导致物体瞬移。
  • 物理/游戏逻辑使用固定时间步长: 累积增量并以固定速率(例如1/60)步进模拟,同时以显示速率渲染——防止隧穿和非确定性。

2. 控制(委托给controls技能)

在实现任何WASD/转向/飞行代码之前,请打开**.grok/skills/controls/SKILL.md**。该技能是以下内容的唯一权威来源:

  • 玩家可感知的A = 左 / D = 右(追逐摄像机,向前移动时)
  • 为什么**KeyA → steer− + yaw += steer * +rate会反转**(最常见的bug)
  • 车辆与FPS(平移≠转向)、固定翼副翼、直升机/无人机说明
  • 强制性自检 + window.__controlsTest探测

不要将genres/racing-kart.md视为转向符号的唯一来源——飞行器、摩托艇和机甲永远不会打开它。

简短提醒(完整细节见controls):

// 车辆偏航体(追逐摄像机):在此基础上,A必须增加偏航
forward = (-sin(yaw), 0, -cos(yaw))
// KeyA → steer = +1;  yaw += steer * turnRate * speedFactor * dt
// 错误(导致反转):KeyA → steer = -1; yaw += steer * turnRate * dt
  • 指针锁定: 仅限鼠标视角——自行实现WASD;点击即玩叠加层;锁定后消失。
  • 使用按住状态 + dt跟踪按键;通过references/input.md统一设备。
  • 完成: 运行controls技能检查清单。仅截图对于车辆/飞行是不够的。

3. 3D方向与世界对象(“侧向/反向”bug)

  • three.js是右手坐标系,+Y向上:+X向右,+Y向上,+Z朝向观察者。网格面朝向+Z;摄像机朝向−Z(经典的“摄像机反向”陷阱)。
  • 像Cone/Cylinder这样的基本体默认指向**+Y** → 需要旋转使尖端对齐前方(geo.rotateX(Math.PI/2))。
  • 使网格朝向forward(网格面朝向**+Z**):最简单正确的方式是mesh.lookAt(mesh.position.clone().add(forward))。要手动构建基向量,将**+Z列设置为forward,并选择保持其为正确右手旋转的X轴(det = +1): xAxis = normalize(cross(up, forward)),然后makeBasis(xAxis, up, forward)。 注意这是cross(up, forward)——不是来自§2的移动方向right = cross(forward, up)。以+Z为目标(而非摄像机的−Z)会翻转X轴符号,使得xAxis × up = forward;坐标系保持右手(无镜像)。不要为网格使用makeBasis(xAxis, up, -forward)——那会将−forward作为目标(摄像机约定),导致网格面朝向后方**。
  • 使摄像机沿forward方向观察(摄像机朝向**−Z**):将+Z列设置为-forward——xAxis = normalize(cross(forward, up)),然后makeBasis(xAxis, up, -forward)(或仅用camera.lookAt(target))。
  • 保持一致的世界上方向up,使物体保持直立;仅旋转平面基本体使其立起。
  • 验证glTF导入方向;使用AxesHelper/ArrowHelper调试。直立自检:角色站在地面上,而非躺下或下沉。

4. 摄像机必须与移动一致

  • 保持专用的**moveForward/moveRight**用于移动,只计算一次,不被摄像机代码修改(别名共享临时向量会导致摄像机与移动不一致——这是一个真实的复现bug)。
  • 第三人称跟随:desired = playerPos + up*height + moveForward*(-followDist);将摄像机向目标插值(使用基于指数的平滑,按增量缩放),lookAt(player)。
  • 分层隔离调试顺序:(1) 按键注册 → (2) 移动方向正确 → (3) 摄像机一致。按此顺序修复。

5. 性能

  • 最小化绘制调用(renderer.info.render.calls,目标<100):共享材质,对重复对象使用InstancedMesh/BatchedMesh,图集。
  • 自行释放GPU资源(geometry/material/texture.dispose()),在关卡切换时执行——three.js不会自动垃圾回收它们。对象池化子弹/敌人/粒子。
  • 无每帧分配(复用临时向量)。压缩纹理;距离使用LOD。

6. 资源(避免生成照片陷阱)

  • 交互式3D元素(武器视图模型、角色、道具、投射物)→ 使用3D几何体/glTF构建,而非生成的图像。一个平面的照片级JPG枪械手部图用作FPS视图模型会看起来很奇怪,无法动画化,并且(JPG没有Alpha通道)会渲染成一个黑框。将真实的3D视图模型作为叠加渲染层挂载到摄像机。
  • 保留图像生成仅用于平面2D资源(纹理、天空/菜单背景、2D精灵、UI美术)。绝对不要使用生成的图片作为3D网格、视图模型或角色替代品——使用3D几何体/glTF构建它们。 在绘制到Canvas/纹理的图像上设置crossOrigin="anonymous"。 请参考**imagine-grok-build**技能(仅2D——图像工具无法生成真正的3D)。
  • 引擎就绪的游戏美术规范 → 打开**game-asset-core(../game-asset-core/)获取默认值 + 盲验 + 重试规则,然后是对应的专家:game-animation-frames(循环/运动法则)、game-tilesets、game-character-consistency、game-ui-icons。这些是质量控制/规范**,而非导出管线。当期望真实美术时,不要发布火柴人占位符。
  • 2D游戏精灵/动画图集 → 运行**generate2dsprite(.grok/skills/generate2dsprite/SKILL.md):纯#FF00FF洋红色imagine_text_to_image图集 + 色度后处理脚本(处理器需要洋红色)。将透明PNG/GIF接入Canvas/Phaser。仍然应用game-asset-core**(以及相关时的动画/角色专家)。
  • 2D地图/关卡/道具包 → 打开**generate2dmap(.grok/skills/generate2dmap/SKILL.md)。对于可玩地图,优先使用仅基础层 + 独立道具/碰撞。浏览器默认:raw_canvas / Phaser。可平铺的地面/墙壁 → 同时也需要game-tilesets**进行2×2接缝检查。
  • 可选的更密集运动 → 运行**video2dsprite(Grok imagine_image_to_video + 沙箱脚本;洋红色基础)。对于清晰的生产主角,优先使用generate2dsprite。使用game-animation-frames进行循环/翻转测试法则;在此沙箱中,优先使用video2dsprite**而非临时仅ffmpeg采集。

7. 音频、保存、手感

  • 音频:在首次用户手势(点击开始)时解锁AudioContext,否则iOS无声;在visibilitychange时重新恢复。(references/audio.md)
  • 保存:使用带有version字段 + 迁移的localStorage/IndexedDB。
  • 手感:屏幕震动、打击停顿、缓动补间、粒子——成本低,感知质量提升大。保持表现层与模拟层分离。

8. 移动端

  • 区分Canvas缓冲区大小与CSS大小;尊重devicePixelRatio。
  • touch-action: none,以基础分辨率信箱适配,处理屏幕方向。
  • 触摸控制(虚拟摇杆 + 动作按钮),目标区域≥44px。

栈/引擎选择

  • 3D → three.js,理想情况下通过**@react-three/fiber + drei**(适合React应用;drei提供指针锁定/控制/加载器)+ @react-three/rapier用于物理/角色控制器。参见references/3d-libs.md。
  • 2D → 原生Canvas 2D足以应对贪吃蛇/俄罗斯方块/Flappy Bird/平台跳跃;仅在类型需要时使用Phaser。
  • 这些游戏依赖未预装——请npm install它们(并确保它们出现在package.json中,以便Vercel构建能获取它们)。

完成标准(在“完成”之前)

  • 无控制台错误加载;可见的游戏玩法(非空白画布)。
  • controls技能自检通过(在向前移动时,从追逐摄像机视角看A = 左 / D = 右;如果反转则翻转一个符号)。非仅截图。
  • 3D直立和摄像机一致自检通过(§3,§4)。
  • 在移动端视口运行,带触摸控制。
  • 生产构建(npm run build)渲染构建输出,而不仅仅是开发模式。
  • 分享/X卡片: 打开**og**技能——自定义public/og.jpg以及在src/lib/og/site.json中设置"type": "x:game"。X使用og:type="x:game"将展开呈现为游戏卡片;不要为此使用twitter:card或发明x:type。当Canvas应用省略site.json字段时,browser-smoke/brand-check会发出警告。

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

Player-facing input signs for browser games: WASD, vehicles, flight, FPS mouse-look, and the #1 failure mode (inverted A/D). Mandatory control self-tests and a tiny test interface so you can verify A turns left before shipping. Load for ANY game with movement, steering, flying, driving, tanks, boats, mechs, drones, planes, karts, third-person follow cams — not only racing. Triggers on "controls", "WASD", "inverted", "steer", "flight", "airplane", "kart", "vehicle", "yaw", "roll", "pitch", "mouse look", "A/D".

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).

相关技能