pixel-art-game-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pixel Art Game Builder

像素艺术游戏构建器

Expert guide for architecting and building pixel art idle/incremental games with procedural sprite generation.

关于架构和构建带程序化精灵生成功能的像素艺术放置/增量游戏的专业指南。

Quick Navigation

快速导航

Need	Go to
Start a new project	Quick Start
Copy working code	templates/
Understand patterns	patterns/
See full example	examples/
Deep reference	references/
CSS/Tailwind setup	assets/

需求	跳转
启动新项目	快速开始
复制可用代码	templates/
了解开发模式	patterns/
查看完整示例	examples/
深度参考文档	references/
CSS/Tailwind配置	assets/

Core Design Philosophy

核心设计理念

Three pillars: Minimal. Luminous. Contemplative.

Constraint = Creativity: Limited palette (12 colors), low resolution (16×16 sprites)
Space speaks: Dark backgrounds, few elements = immensity feeling
Light guides: Important elements glow (higher rarities shine more)
Movement breathes: Slow, organic animations (minimum 500ms cycles)
Zero pressure: NO timers, NO deadlines, NO FOMO, NO negative messages

三大支柱： 极简、明亮、禅意。

限制催生创意: 有限调色板（12色）、低分辨率（16×16精灵）
留白传递质感: 深色背景、少量元素 = 营造广袤感
光线引导注意力: 重要元素发光（稀有度越高亮度越高）
动效赋予生机: 缓慢、自然的动画（最低500ms周期）
零压力体验: 无计时器、无截止日期、无FOMO、无负面提示信息

Quick Start

快速开始

bash

npm create vite@latest my-idle-game -- --template react-ts
cd my-idle-game
npm install zustand immer
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

Then copy files from assets/ for CSS and Tailwind config.

bash

npm create vite@latest my-idle-game -- --template react-ts
cd my-idle-game
npm install zustand immer
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

随后复制 assets/ 目录下的CSS和Tailwind配置文件即可。

Critical Implementation Rules

关键实现规则

Pixel Art Sprites (16×16)

像素艺术精灵（16×16）

javascript

// MANDATORY for pixel-perfect rendering
ctx.imageSmoothingEnabled = false;

css

/* CSS for any sprite element */
.sprite { image-rendering: pixelated; }

4 colors max per sprite: base, highlight, shadow, outline
12×12 usable zone (2px margin for glow effects)
Scale 4× when displaying (16×16 → 64×64)
NO antialiasing, NO gradients

javascript

// MANDATORY for pixel-perfect rendering
ctx.imageSmoothingEnabled = false;

css

/* CSS for any sprite element */
.sprite { image-rendering: pixelated; }

每个精灵最多4种颜色: 基础色、高光色、阴影色、轮廓色
12×12可用区域（预留2px边距用于发光效果）
展示时缩放4倍（16×16 → 64×64）
无抗锯齿、无渐变

Color Palette (12 colors only)

颜色调色板（仅12色）

typescript

const PALETTE = {
  deepBlack: '#0a0a0f',      // Main background
  spaceGray: '#1a1a2e',      // Panels
  borderGray: '#2d2d44',     // Borders
  neonCyan: '#00fff5',       // Primary actions, RARE
  softMagenta: '#ff6bcb',    // Notifications, EPIC
  cosmicGold: '#ffd93d',     // Rewards, LEGENDARY
  validGreen: '#39ff14',     // Success, UNCOMMON
  alertRed: '#ff4757',       // Alerts (rare use)
  mysteryPurple: '#6c5ce7',  // Hidden/secret
  mainWhite: '#e8e8e8',      // Body text, COMMON
  secondaryGray: '#a0a0a0',  // Disabled
  interactiveCyan: '#7fefef' // Links
};

const RARITY_COLORS = {
  common: PALETTE.secondaryGray,
  uncommon: PALETTE.validGreen,
  rare: PALETTE.neonCyan,
  epic: PALETTE.softMagenta,
  legendary: PALETTE.cosmicGold,
};

typescript

const PALETTE = {
  deepBlack: '#0a0a0f',      // Main background
  spaceGray: '#1a1a2e',      // Panels
  borderGray: '#2d2d44',     // Borders
  neonCyan: '#00fff5',       // Primary actions, RARE
  softMagenta: '#ff6bcb',    // Notifications, EPIC
  cosmicGold: '#ffd93d',     // Rewards, LEGENDARY
  validGreen: '#39ff14',     // Success, UNCOMMON
  alertRed: '#ff4757',       // Alerts (rare use)
  mysteryPurple: '#6c5ce7',  // Hidden/secret
  mainWhite: '#e8e8e8',      // Body text, COMMON
  secondaryGray: '#a0a0a0',  // Disabled
  interactiveCyan: '#7fefef' // Links
};

const RARITY_COLORS = {
  common: PALETTE.secondaryGray,
  uncommon: PALETTE.validGreen,
  rare: PALETTE.neonCyan,
  epic: PALETTE.softMagenta,
  legendary: PALETTE.cosmicGold,
};

Game Loop Pattern (100ms tick)

游戏循环模式（100ms tick）

typescript

useEffect(() => {
  const interval = setInterval(() => {
    const now = Date.now();
    const delta = (now - lastTick) / 1000;

    // Update resources
    addCredits(incomePerSecond * delta);
    regenerateEnergy(delta);

    setLastTick(now);
  }, 100);
  return () => clearInterval(interval);
}, [incomePerSecond, lastTick]);

typescript

useEffect(() => {
  const interval = setInterval(() => {
    const now = Date.now();
    const delta = (now - lastTick) / 1000;

    // Update resources
    addCredits(incomePerSecond * delta);
    regenerateEnergy(delta);

    setLastTick(now);
  }, 100);
  return () => clearInterval(interval);
}, [incomePerSecond, lastTick]);

State Management (Zustand + Immer)

状态管理（Zustand + Immer）

typescript

import { create } from 'zustand';
import { persist } from 'zustand/middleware';
import { immer } from 'zustand/middleware/immer';

const useGameStore = create<GameState>()(
  persist(
    immer((set, get) => ({
      credits: 0,
      energy: 100,
      addCredits: (amount) => set((s) => { s.credits += amount }),
    })),
    { name: 'game-save' }
  )
);

typescript

import { create } from 'zustand';
import { persist } from 'zustand/middleware';
import { immer } from 'zustand/middleware/immer';

const useGameStore = create<GameState>()(
  persist(
    immer((set, get) => ({
      credits: 0,
      energy: 100,
      addCredits: (amount) => set((s) => { s.credits += amount }),
    })),
    { name: 'game-save' }
  )
);

Templates (Copy & Use)

模板（复制即可使用）

Ready-to-use code in templates/:

Template	Description
`game-loop.tsx`	Hook for 100ms game tick with delta time
`save-system.ts`	Zustand persist pattern with migration
`progression.ts`	Scaling formulas (exponential costs, diminishing returns)
`sprite-renderer.tsx`	Canvas component with pixel-perfect rendering

templates/ 目录下提供开箱即用的代码：

模板	描述
`game-loop.tsx`	支持delta时间的100ms游戏tick钩子
`save-system.ts`	支持版本迁移的Zustand持久化模式
`progression.ts`	数值缩放公式（指数成本、收益递减）
`sprite-renderer.tsx`	支持像素级完美渲染的Canvas组件

Patterns (Understand & Adapt)

模式（理解后可适配改造）

Conceptual guides in patterns/:

Pattern	Description
`resource-system.md`	Structure currencies, caps, regeneration
`upgrade-tree.md`	Linear upgrades, skill trees, prestige unlocks
`prestige-loop.md`	Reset mechanics, meta-progression, permanent bonuses
`procedural-sprites.md`	Generate varied sprites from seeds

patterns/ 目录下提供概念指南：

模式	描述
`resource-system.md`	货币、上限、回复机制的结构设计
`upgrade-tree.md`	线性升级、技能树、转生解锁设计
`prestige-loop.md`	重置机制、元 progression、永久增益设计
`procedural-sprites.md`	基于种子生成多样化精灵的方法

Examples

示例

Working code in examples/:

Example	Description
`minimal-idle-game.tsx`	Complete ~150 line idle game with resources, upgrades, save

examples/ 目录下提供可运行的代码：

示例	描述
`minimal-idle-game.tsx`	约150行的完整放置游戏，包含资源、升级、存档功能

Deep References

深度参考

Detailed documentation in references/:

Reference	When to use
`architecture.md`	Full project structure, types, stores
`sprite-system.md`	Canvas API, color derivation, caching
`game-mechanics.md`	Economy, scanning, progression formulas
`ui-patterns.md`	Components, layouts, animations
`content-structure.md`	Data structure for items, sectors, upgrades

references/ 目录下提供详细文档：

参考文档	使用场景
`architecture.md`	完整项目结构、类型定义、store设计
`sprite-system.md`	Canvas API、颜色衍生、缓存机制
`game-mechanics.md`	经济系统、探索、 progression 公式
`ui-patterns.md`	组件、布局、动画设计
`content-structure.md`	道具、关卡、升级的数据结构设计

Design Pillars (Non-Negotiable)

设计支柱（不可修改）

Immediate Clarity: Every button has text label, max 3 actions visible
Progressive Depth: New content unlocks over time
Emotional Collection: Every item has narrative description ≤140 chars
Zero Pressure: NO timers, NO deadlines, NO FOMO
Mobile First: Touch targets ≥44px, breakpoints 320/768/1024px

即时清晰度: 每个按钮都有文本标签，最多同时展示3个操作
渐进式深度: 新内容随时间逐步解锁
情感化收集: 每个道具的叙事描述不超过140字
零压力体验: 无计时器、无截止日期、无FOMO
移动端优先: 触控目标≥44px，断点适配320/768/1024px

Writing Style

文案风格

Voice: Calm, melancholic, subtle humor
Rules: ≤140 chars, NO "!", NO CAPS, NO imperatives

Templates:

Funny: "[Object]. [Absurd observation]. [Punchline]."
Tender: "[Object]. [Human detail]. [Universal truth]."
Weird: "[Object]. [Strange property]. [Acceptance]."

语气: 平静、略带忧郁、暗藏幽默感
规则: 单条文案≤140字，无感叹号、无全大写、无祈使句

模板：

幽默风: "[物品]. [荒诞观察]. [笑点]."
温柔风: "[物品]. [人性化细节]. [普适真理]."
怪诞风: "[物品]. [奇异属性]. [接受设定]."

Performance Targets

性能指标

Metric	Target
Bundle size	<200KB gzipped
FPS idle	≥30
Memory	<100MB

指标	目标值
包体积	gzip压缩后<200KB
空闲FPS	≥30
内存占用	<100MB

DO's and DON'Ts

注意事项

DO ✓

Pixel-perfect rendering (
```
imageSmoothingEnabled = false
```
)
4-color sprites maximum
12-color palette only
≥44px touch targets
Cache generated sprites
Support reduced-motion

DON'T ✗

Antialiasing on sprites
Gradients in pixel art
Icon-only buttons
Stats in item descriptions
Timers or countdowns
Negative failure messages
Nested modals

推荐 ✓

像素级完美渲染（
```
imageSmoothingEnabled = false
```
）
每个精灵最多4种颜色
仅使用12色调色板
触控目标≥44px
缓存生成的精灵
支持reduced-motion（减少动画）系统设置

禁止 ✗

精灵使用抗锯齿
像素艺术中使用渐变
仅用图标无文本的按钮
道具描述中加入数值属性
计时器或倒计时
负面失败提示
嵌套模态框