# Agent Sprite Forge: tạo bộ sprite 2D từ một ảnh gốc — hướng dẫn cài đặt và dùng

> Agent Sprite Forge là bộ skill cho các agent lập trình (Claude Code, Codex, Grok) để tạo sprite 2D và bản đồ từ câu lệnh. Bạn duyệt một ảnh gốc của nhân vật, agent tạo từng hành động (đứng yên, đi, chạy, đánh…) rồi đóng gói cho Godot, Aseprite hoặc game web. Cài đặt khá gọn nếu bạn đã quen dùng terminal và có Python, nhưng cần thêm ffmpeg nếu làm video.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-07-07 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/agent-sprite-forge-tao-bo-sprite-2d-tu-mot-anh-goc

Agent Sprite Forge là một bộ "agent skill" giúp tạo sprite 2D cho game từ câu lệnh tiếng người. Nó chạy bên trong Claude Code (dạng plugin), Codex hoặc Grok. Bạn mô tả nhân vật, duyệt một ảnh gốc, và agent làm nốt phần còn lại: ra các hành động của nhân vật, tách nền, làm cho vòng lặp mượt, rồi xuất file cho engine game.

Vấn đề repo giải quyết rất thực tế. Làm animation cho một nhân vật thường mất nhiều ngày: vẽ từng khung, cắt khung, căn chân cho khỏi "trượt" khi chạy, chỉnh tốc độ. Repo này tự động hóa chuỗi đó. Phần tạo ảnh do mô hình AI làm, còn phần kiểm tra, tách nền, căn khung, chọn vòng lặp, đóng gói do các công cụ Python làm theo cách có thể đo được, không phải ước chừng.

Bạn nên xem repo này nếu bạn là lập trình viên game indie, người làm prototype, hoặc người làm kinh doanh muốn có nhân vật và hiệu ứng cho một game nhỏ mà không thuê họa sĩ ngay. Hiện repo có khoảng 5561 sao và 537 fork, giấy phép MIT, và vẫn được cập nhật trong 3 tháng gần đây. Điểm đáng giá nhất: bạn duyệt đúng một ảnh, cả bộ hành động sinh ra từ ảnh đó nên nhân vật giữ được diện mạo nhất quán.

```repo
- repo | 0x0funky/agent-sprite-forge
- kind | Skill
- desc | Bộ skill cho Claude Code, Codex và Grok: từ một ảnh nhân vật được duyệt, tạo cả bộ hành động, ảnh PNG trong suốt, GIF và gói xuất cho engine game.
- stars | 5.6k
- lang | Python
- license | MIT
```

## Agent Sprite Forge làm được gì

Dưới đây là các khả năng chính, giải thích theo lợi ích khi dùng thật.

### Từ một ảnh gốc ra cả bộ hành động

Bạn tạo một "master still" (ảnh gốc của nhân vật). Từ ảnh đó, agent tạo mỗi hành động một đoạn video ngắn (idle, walk, run, attack, jump, hurt…). Lợi ích: nhân vật không bị "đổi mặt" giữa các hành động, vì tất cả cùng xuất phát từ một ảnh bạn đã duyệt.

### Kiểm tra và loại bản hỏng tự động

Mỗi lần tạo (take) đều bị kiểm tra: kích thước vùng, bàn chân, giống nhân vật không, có zoom hay quay người không, nền có sạch không, có vật thừa không, chuyển động và tư thế kết thúc ra sao, màu có lem không. Bản không đạt sẽ được tạo lại kèm câu sửa lỗi. Bạn đỡ phải ngồi soi từng bản.

### Tách nền mềm, căn khung, chọn vòng lặp

Bộ tách nền mềm (soft matte) giúp viền nhân vật không bị ám màu tím. README ghi số đo: viền ám màu giảm từ 0,704 xuống 0, và thời gian tách 145 khung giảm từ 271 giây xuống 44 giây. Vòng lặp (chạy, đi) được chọn bằng phép đo. Tốc độ chạy được đo từ bàn chân chạm đất nên chân không trượt trên nền.

### Chỉnh nhịp cho hành động ngắn

Mô hình video hay biến một cú đánh nhanh thành cảnh quay chậm. Lệnh `retime --auto-oneshot` cắt các đoạn đứng hình và ghim thời điểm trúng đòn: ví dụ trong README, cú đánh từ 4,1 giây còn 0,7 giây.

### Hoàn thiện HD hoặc pixel

Mặc định là bản HD, kèm "khóa màu" để màu thiết kế không bị trôi khi chi tiết di chuyển nhanh. Khi bạn yêu cầu, có thêm bản pixel sắc nét: bảng màu tối đa 32 màu, viền chọn lọc, alpha chỉ có hai mức.

### Hai hướng pixel art nâng cao

- **Hibit**: không bắt mô hình vẽ "pixel art" (dễ ra pixel giả, to nhỏ không đều). Thay vào đó xin ảnh phẳng, không viền, rồi tạo pixel sau bằng bảng màu học từ chính ảnh và phép thu nhỏ 8x8.
- **Pixel looks**: dùng một sprite bạn thích làm mẫu cho cả dàn nhân vật. Công cụ đọc ảnh vào lưới pixel thật, giảm xuống bảng màu và khép viền theo quy tắc. Trong ví dụ của README, một nhân vật 33x55 pixel chỉ có 48 màu.

Cả hai chỉ chạy khi bạn yêu cầu. Chế độ HD mặc định và các kiểu hoàn thiện cũ không bị đổi.

### Xuất cho engine và làm bản đồ

Gói xuất gồm animation.json 3.0 kèm atlas PNG, WebM (VP9 alpha), MP4, Godot SpriteFrames và Sprite3D, Aseprite JSON, và bản đồ cho Tiled, Godot, LDtk. Với hiệu ứng (FX), README khuyên dùng thêm thư viện pixelfx của bên thứ ba (cần Node 18+), nhưng đó là phần tùy chọn.

## Cần chuẩn bị gì

Chỉ những gì README nêu:

- **Python** và pip. Các gói yêu cầu: numpy (từ 1.26), Pillow (từ 10.1), scipy (từ 1.11).
- **Một agent**: Claude Code, Codex hoặc Grok.
- **ffmpeg 5.1 trở lên** có trong `PATH` nếu bạn làm video (tạo hành động động).
- **Nguồn tạo ảnh/video**: khóa API của OpenAI, Google Gemini, xAI, BytePlus hoặc fal.ai (nếu bạn cấu hình), hoặc nếu không có khóa thì dùng Codex CLI hay Grok CLI đã đăng nhập. Cuối cùng mới là "code art" làm phương án dự phòng.
- **Git** để clone repo (với cách cài cho Codex và Grok).
- **Node 18+**: chỉ cần nếu bạn muốn dùng pixelfx cho hiệu ứng.

README phần đã cung cấp chưa nêu yêu cầu cụ thể về hệ điều hành hay phần cứng (GPU). Có nhắc việc đã xử lý riêng cho Windows (thư mục chạy trong sandbox của Codex, dọn file bị khóa, console cp1252/cp950). Mục khóa API nằm ở phần "Setting API keys" trong README, bạn mở đó để xem chi tiết.

```note
Nếu bạn cấu hình khóa API, mỗi ảnh và mỗi clip video tạo ra có thể phát sinh chi phí ở nhà cung cấp. Không dán khóa vào chat hay đưa lên repo công khai. Hãy kiểm tra gói cước của bạn trước khi tạo hàng loạt.
```

## Cài đặt từng bước

```steps
- Chọn agent | Quyết định bạn dùng Claude Code, Codex hay Grok
- Cài skill | Chạy lệnh cài tương ứng với agent đó
- Cài thư viện Python | Cài numpy, Pillow, scipy
- Cài ffmpeg | Cần nếu bạn làm video, bản 5.1 trở lên
- Mở phiên agent mới | Để skill được nạp
- Tạo ảnh gốc | Gọi $generate2dsprite với mô tả nhân vật
```

### Cách A: cài cho Claude Code (plugin)

Mở terminal (PowerShell trên Windows, Terminal trên macOS/Linux) ở bất kỳ thư mục nào và chạy ba lệnh sau. Hai lệnh đầu thêm kho plugin rồi cài plugin. Lệnh thứ ba cài các thư viện Python mà các công cụ cần.

```bash
claude plugin marketplace add 0x0funky/agent-sprite-forge --sparse .claude-plugin skills
claude plugin install agent-sprite-forge@agent-sprite-forge
python -m pip install "numpy>=1.26" "Pillow>=10.1" "scipy>=1.11"
```

Cờ `--sparse` chỉ tải phần manifest của plugin và các skill, không tải ảnh và video minh họa nên nhẹ hơn nhiều. Người mới hay vấp ở chỗ gõ nhầm dấu ngoặc kép trong lệnh pip. Hãy giữ nguyên dấu ngoặc để shell không hiểu `>=` là chuyển hướng ra file.

### Cách B: cài cho Codex

Cách này cần clone repo. Lệnh `cd` đưa bạn vào thư mục vừa tải, và các lệnh sau phải chạy trong thư mục đó.

```bash
git clone https://github.com/0x0funky/agent-sprite-forge.git
cd agent-sprite-forge
python -m pip install -r requirements.txt
python tools/install_skills.py --apply --host codex
```

Lệnh `install_skills.py --apply` chép các skill vào nơi Codex đọc. README nói lệnh này sao lưu bản đã cài trước đó và ghi một bảng sha256. Sau này bạn có thể kiểm tra xem file có bị lệch không bằng `python tools/install_skills.py --check --host codex`.

### Cách C: cài cho Grok

Dùng chính bản clone ở trên, chỉ đổi tham số host:

```bash
python tools/install_skills.py --apply --host grok
```

Skill sẽ được ghi vào `~/.grok/skills`. README còn nói `--host agents` ghi vào `~/.agents/skills`, và `--dest <thư mục>` ghi vào một thư mục skill bất kỳ.

### Cài ffmpeg và mở phiên mới

Nếu làm video, README yêu cầu ffmpeg 5.1 trở lên có trong `PATH`. README không đưa lệnh cài ffmpeg, bạn cài theo trang chủ ffmpeg hoặc trình quản lý gói của máy mình. Sau khi cài xong, hãy mở một phiên agent mới để skill được nạp. Nếu bạn dùng khóa API, xem mục "Setting API keys" trong README. Nếu không, agent dùng Codex hoặc Grok CLI đã đăng nhập sẵn của bạn.

## Kiểm tra đã chạy được chưa

README không đưa một lệnh "hello world" riêng. Cách kiểm tra thực tế, bám theo tư liệu, như sau:

1. Với Codex, chạy lệnh kiểm tra lệch bản cài:

```bash
python tools/install_skills.py --check --host codex
```

2. Mở phiên agent mới, gõ thử câu tạo ảnh gốc dưới đây. Nếu skill đã nạp, agent sẽ chạy `master_still.py generate --takes 3`, đưa bạn xem 3 bản, rồi sau khi bạn duyệt sẽ ghi kết quả vào `master.json`.

```text
Use $generate2dsprite to make a master still of Aria, a young swordswoman hero: short dark hair, a teal hooded cloak, a long red scarf and one steel sword. Side view, facing right, HD.
```

Nếu agent không nhận ra `$generate2dsprite`, thường là bạn chưa mở phiên mới hoặc skill chưa được cài vào đúng thư mục. Xem phần lỗi bên dưới.

## Dùng vào việc thật

### Dev indie cần nhân vật chính cho game platformer

Bạn đang làm prototype game đi cảnh và chưa có họa sĩ. Bạn tạo ảnh gốc bằng câu lệnh ở phần kiểm tra, xem 3 bản, chọn một và duyệt. Skill ghi nhận ảnh đó, đã tách nền và căn vào khung chuẩn (README nêu một nhân vật "hero" cao 788 px trong khung 1024x1024). Nếu một bản gần đúng, agent sửa bằng `master_still.py edit` với câu dạng "THE ONLY CHANGE: ...".

Tiếp theo, bạn gõ:

```text
Use $video2dsprite to animate the approved Aria master: idle, walk, run, attack, jump and hurt. Package them for Godot and the web.
```

Kết quả: sáu hành động, mỗi hành động qua kiểm tra, tách nền, căn khung và đóng gói cho Godot và web.

> Duyệt đúng một ảnh gốc, còn lại để công cụ đo và đóng gói.
>
> — Ông T

### Làm nhân vật pixel art cho game retro

Bạn muốn nhân vật nhỏ, đúng kiểu pixel cổ điển. Thay vì xin mô hình vẽ pixel art, bạn dùng kiểu hoàn thiện pixel hoặc hibit. Với hibit, README nêu `master_still.py --finish hibit` (ảnh phẳng, không viền) và `sprite_set.py plan --finish hibit` cho cả bộ hành động, tạo hero 80 px, 12 khung hình/giây. Bạn chỉ cần nói với agent rằng bạn muốn kiểu hibit hoặc pixel, vì chúng chỉ chạy khi được yêu cầu. Kết quả: mỗi nhân vật có một bảng màu riêng, các hành động dùng chung bảng màu và viền của hành động đầu.

### Làm cả dàn nhân vật có cùng phong cách

Bạn có một sprite mẫu ưng ý và cần thêm quái vật, pháp sư cho cùng một màn chơi. Với công cụ `pixel_look.py`, bạn dùng `ask-master` và `master` để đọc sprite mẫu thành bản 1x chuẩn, rồi `ask-cast` và `cast` để vẽ thêm các nhân vật bên cạnh mẫu. Ví dụ trong README là pháp sư, hiệp sĩ xương và rồng băng, mỗi nhân vật 48 màu. Lệnh `lineup` xếp tất cả lên cùng một đường nền và báo chiều cao, tiện để bạn so sánh tỷ lệ.

### Làm nền và hiệu ứng cho cảnh game

Sau khi có nhân vật, bạn cần nền và hiệu ứng. Với hibit, `hibit_plate.py` tạo nền 480x270 với bảng 14 màu. Với hiệu ứng, README khuyên dùng pixelfx (render miễn phí trên máy, cần Node 18+), hoặc dùng đường tạo ảnh, tốn một ảnh mỗi hiệu ứng nhưng luôn có sẵn. `fx_pixelfx.py check` sẽ chọn đường giúp bạn. Kết quả là các khung hiệu ứng đi cùng phong cách game, kèm file `CREDITS.txt` khi dùng pixelfx.

## Lỗi hay gặp và cách xử lý

### Agent không nhận ra lệnh $generate2dsprite

Nguyên nhân hay gặp: bạn chưa mở phiên agent mới sau khi cài, hoặc skill chưa vào đúng thư mục. Hãy đóng phiên cũ, mở lại. Với Codex, chạy `python tools/install_skills.py --check --host codex` để xem bản cài có lệch không. Với Grok, nhớ dùng `--host grok`.

### Báo thiếu numpy, Pillow hoặc scipy

Nghĩa là bước `pip install` chưa chạy hoặc chạy vào Python khác với Python mà agent dùng. Chạy lại đúng lệnh pip ở phần cài đặt. Nếu máy có nhiều bản Python, hãy dùng cùng một bản cho cả cài đặt và chạy.

### Lỗi khi tạo video: không tìm thấy ffmpeg

README yêu cầu ffmpeg 5.1+ có trong `PATH`. Sau khi cài, mở terminal mới rồi gõ `ffmpeg -version` để chắc rằng máy nhận ra. Bản quá cũ có thể không đạt yêu cầu.

### Không tạo được ảnh hoặc video

Công cụ sẽ thử khóa API của bạn trước, rồi đến Codex hoặc Grok CLI đã đăng nhập, cuối cùng mới đến code art. Nếu cả hai nguồn đầu chưa sẵn sàng, bạn sẽ chỉ nhận kết quả kém hơn. Hãy kiểm tra đã đăng nhập CLI chưa, hoặc đã cấu hình khóa API đúng theo mục "Setting API keys" chưa.

### Bản tạo ra bị bỏ hoặc phải thử lại nhiều lần

Đây là hành vi có chủ đích: các bản không đạt kiểm tra sẽ bị tạo lại. Với khóa API, mỗi lần thử có thể tốn chi phí. Nên làm thử một hành động trước khi chạy cả bộ.

## Có nên dùng không

**Điểm mạnh.** Quy trình trọn vòng từ ảnh gốc đến file cho engine. Có kiểm tra chất lượng và số đo cụ thể thay vì chỉ "trông có vẻ ổn". Hỗ trợ ba agent phổ biến, giấy phép MIT, repo còn được cập nhật. Xuất được cho Godot, Aseprite, Tiled, LDtk và web.

**Giới hạn.** Công cụ chạy qua dòng lệnh và agent, nên người chưa từng mở terminal sẽ thấy hơi khó ở bước cài. Chất lượng phụ thuộc mô hình tạo ảnh và video bạn chọn. Có thể phát sinh chi phí khi dùng khóa API. Tôi chưa thấy trong tư liệu thông tin về yêu cầu GPU hay hệ điều hành cụ thể, nên bạn nên đọc README đầy đủ trước khi cài. Phần README mình có chưa đầy đủ, vài chi tiết (ví dụ lệnh `sprite_set.py` đầy đủ) bạn cần xem trực tiếp trong README của repo.

**Khi nào chọn cách khác.** Nếu bạn cần một nhân vật vẽ tay có phong cách riêng rất đặc thù, hoặc cần kiểm soát từng pixel, thì họa sĩ hoặc Aseprite vẫn phù hợp hơn. Còn nếu bạn cần nhanh một bộ sprite nhất quán để thử ý tưởng game, repo này đáng để thử.

## Câu hỏi thường gặp

### Agent Sprite Forge có miễn phí không?

Repo dùng giấy phép MIT nên bạn dùng và sửa được. Tuy nhiên việc tạo ảnh và video đi qua khóa API (OpenAI, Gemini, xAI, BytePlus, fal.ai) hoặc Codex/Grok CLI của bạn, nên chi phí phụ thuộc gói cước của các dịch vụ đó. README chưa nêu bảng giá.

### Dùng được với những agent nào?

README hỗ trợ Claude Code (dạng plugin), Codex và Grok. Ngoài ra có tuỳ chọn `--host agents` và `--dest <thư mục>` để cài vào thư mục skill khác.

### Cần GPU hay máy mạnh không?

Tư liệu mình có không nói về yêu cầu GPU. Phần tạo ảnh và video đi qua dịch vụ hoặc CLI bạn cấu hình, còn công cụ Python chạy trên máy bạn. Chi tiết phần cứng hãy xem README đầy đủ.

### Chạy trên Windows được không?

README ghi repo đã được xử lý riêng cho Windows: thư mục chạy trong sandbox của Codex, dọn file bị khóa, và console cp1252/cp950. Tuy nhiên tư liệu chưa nêu danh sách hệ điều hành chính thức.

### Có cần cài ffmpeg không?

Có, nếu bạn làm video (các hành động động). README yêu cầu ffmpeg 5.1 trở lên có trong PATH. README không đưa lệnh cài ffmpeg.

### Dữ liệu của tôi có an toàn không?

Các công cụ Python chạy trên máy bạn, nhưng ảnh và video được tạo qua dịch vụ hoặc CLI bạn chọn, nên tuân theo chính sách của nhà cung cấp đó. Tư liệu chưa nêu thêm về quyền riêng tư. Bạn nên giữ khóa API kín và không đưa lên nơi công khai.

### Khác gì việc nhờ AI vẽ sprite sheet trực tiếp?

Theo README, cách cũ là cắt khung từ một sheet do mô hình ảnh tạo. Từ bản 0.4, repo tạo một clip video cho mỗi hành động từ cùng một ảnh gốc, rồi kiểm tra, tách nền, căn khung và đóng gói. README nêu số đo trước và sau, ví dụ số màu trên mỗi khung của cáo pixel giảm từ 594–709 xuống 16–19.
