# agent-sprite-forge: tạo sprite game từ prompt — hướng dẫn cài đặt và dùng

> agent-sprite-forge là bộ Agent Skill cho Claude Code, Codex và Grok, giúp tạo nhân vật 2D, animation, sprite sheet, map và hiệu ứng từ prompt. Repo có pipeline Python để xử lý, kiểm tra, đóng gói cho Godot, Aseprite và web game. Cài đặt tương đối dễ nếu bạn đã có Python; API key là tùy chọn tùy tuyến tạo ảnh bạn dùng.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-04-30 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/agent-sprite-forge-tao-sprite-game-tu-prompt

agent-sprite-forge là một Agent Skill giúp biến một ảnh nhân vật được duyệt thành cả bộ sprite 2D sẵn dùng cho game. Công cụ có thể tạo ảnh tĩnh, animation, sprite sheet, map, PNG nền trong suốt, GIF và các gói xuất cho Godot, Aseprite hoặc web game.

Repo phù hợp với người làm game indie, lập trình viên mới, người thiết kế nhân vật và nhóm nhỏ muốn thử nhanh nhiều chuyển động mà không phải tự cắt, căn chỉnh, key màu và đóng gói từng frame. Điểm đáng giá nhất là quy trình bắt đầu từ một master still. Sau khi bạn duyệt ảnh gốc, công cụ dùng ảnh đó làm chuẩn cho các hành động như idle, walk, run, attack, jump và hurt.

Pipeline có các bước kiểm tra và xử lý khá đầy đủ: chọn frame, loại nền, căn vị trí, đo vòng lặp, đổi tốc độ, khóa màu và tạo file cho engine. Repo hiện có khoảng 5663 sao và 550 fork, dùng giấy phép MIT.

```repo
- repo | 0x0funky/agent-sprite-forge
- kind | Skill
- desc | Agent Skill biến một ảnh nhân vật thành bộ sprite 2D, map, PNG trong suốt và GIF động cho game.
- stars | 5.7k
- lang | Python
- license | MIT
```

## agent-sprite-forge làm được gì

### Tạo master still từ mô tả

Bạn mô tả nhân vật bằng prompt, chẳng hạn một nữ kiếm sĩ nhìn ngang, áo choàng xanh và khăn đỏ. Skill tạo nhiều lựa chọn rồi cho bạn duyệt một ảnh. Ảnh được chọn trở thành chuẩn về tỷ lệ, dáng, màu và cách nhân vật xuất hiện trong các bước sau.

Việc có một ảnh chuẩn giúp giảm tình trạng mỗi animation trông như một nhân vật khác. Repo cũng ghi lại ảnh được duyệt trong `master.json`, để các bước tiếp theo dùng cùng một nguồn.

### Tạo nhiều hành động từ một nhân vật

Từ master still, `sprite_set.py` tạo clip image-to-video cho từng hành động. Bạn có thể yêu cầu idle, walk, run, attack, jump và hurt trong cùng một bộ.

Mỗi take được kiểm tra về diện tích nhân vật, bàn chân, nhận diện nhân vật, phóng to, xoay hướng, viền, nền, vật thể thừa, chuyển động, tư thế cuối, màu bị lem và thời lượng. Nếu kết quả chưa đạt, pipeline có thể tạo lại với các điều kiện sửa cụ thể.

### Xử lý frame để dùng trực tiếp trong game

Các công cụ Python thực hiện key nền, căn đăng ký giữa các frame, chọn loop, đổi tốc độ và đóng gói. Với các đòn đánh hoặc hành động một lần, `retime --auto-oneshot` có thể bỏ các đoạn đứng yên thừa và đưa cú đánh về tốc độ phù hợp hơn với game.

Pipeline cũng có bước khóa màu. Mục tiêu là hạn chế việc màu tóc, áo hoặc giày bị thay đổi giữa các frame do model video tạo ra.

### Tạo pixel look và hibit

Repo có hai hướng tạo pixel art.

`pixel_look.py` đọc lại ảnh theo lưới riêng của hình, lấy màu đại diện cho từng ô, giảm bảng màu và xử lý đường viền. Cách này phù hợp khi bạn có một sprite tham chiếu và muốn các nhân vật khác giữ cùng kích thước pixel, tỷ lệ và phong cách.

Hibit bắt đầu từ ảnh phẳng, không viền, rồi tạo pixel sau. Công cụ dùng bảng màu học từ ảnh nguồn, giảm ảnh bằng majority vote trên ô 8x8, hạn chế nhấp nháy màu, giữ mắt và điểm sáng, dùng alpha nhị phân và có thể tạo viền từ chính màu của sprite.

### Tạo dàn nhân vật và nhiều hướng nhìn

Bạn có thể tạo thêm nhân vật bên cạnh master bằng các lệnh `ask-cast` và `cast`. Công cụ cố giữ kích thước pixel, chiều cao và bảng màu nhất quán giữa các nhân vật.

Các lệnh `ask-pose`, `pose`, `ask-view` và `view` dùng master để tạo tư thế, góc nhìn bên hoặc góc nhìn sau. `lineup` đặt các nhân vật trên cùng một đường nền và báo chiều cao, giúp bạn kiểm tra trước khi đưa vào game.

### Tạo map và hiệu ứng

Repo có hướng tạo background cho game. `hibit_plate.py` hỗ trợ background 480x270, bảng màu 14 màu, làm mượt kiểu giấy cắt và shade map cho ánh sáng hoặc hiệu ứng trúng đòn.

Với hiệu ứng pixel, repo khuyến nghị pixelfx. Nếu pixelfx có trên máy, `fx_pixelfx.py check` có thể chọn tuyến này. Nếu không, công cụ dùng tuyến ảnh để tạo sheet hiệu ứng rồi xử lý bằng `hibit_fx.py pixelize`.

### Xuất cho nhiều công cụ

Pipeline có thể tạo `animation.json` 3.0, PNG atlas, WebM VP9 có alpha và MP4 packed-alpha. Repo cũng nêu các đầu ra cho Godot SpriteFrames, Godot Sprite3D, Aseprite JSON, Tiled, Godot và LDtk.

Điều này có nghĩa là bạn không chỉ nhận ảnh rời. Bạn còn có cấu trúc để đưa animation và map vào công cụ phát triển game, miễn là bạn kiểm tra lại đầu ra trong engine của mình.

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

Bạn cần một máy có Python và terminal. Repo dùng Python là ngôn ngữ chính. README ghi lệnh cài dependencies bằng `requirements.txt`; riêng cài plugin Claude Code dùng `numpy>=1.26`, `Pillow>=10.1` và `scipy>=1.11`.

Bạn cần chọn một môi trường agent được repo hỗ trợ: Claude Code, Codex hoặc Grok. Claude Code dùng plugin. Codex và Grok dùng các skill được cài từ bản clone của repo.

Nếu muốn xử lý video, `ffmpeg 5.1+` phải có trên `PATH`. README không ghi giới hạn hệ điều hành cụ thể, nhưng có nêu pipeline đã được xử lý cho Windows, bao gồm thư mục sandbox của Codex, file bị khóa và console cp1252/cp950.

API key không bắt buộc trong mọi trường hợp. README ghi công cụ sẽ dùng API key nếu bạn cấu hình cho OpenAI, Google Gemini, xAI, BytePlus hoặc fal.ai. Nếu không có key, agent dùng Codex CLI hoặc Grok CLI đã đăng nhập; nếu các tuyến đó cũng không có, code art là phương án cuối.

Nếu muốn dùng hiệu ứng pixelfx, bạn cần cài riêng dự án đó và Node 18+. README chỉ rõ pixelfx là một dự án MIT độc lập. Bạn cũng cần xem phần `Setting API keys` trong README để biết cách cấu hình key; phần tư liệu được cung cấp ở đây không có chi tiết tên biến môi trường.

```note
API key có thể phát sinh chi phí theo nhà cung cấp. Chỉ cấp key cho môi trường bạn kiểm soát, không đưa key vào prompt, ảnh, file commit hoặc thư mục chia sẻ.
```

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

```steps
- Chọn môi trường | Chọn Claude Code, Codex hoặc Grok
- Cài repo và thư viện | Clone repo rồi cài dependencies Python
- Cài skill | Đăng ký plugin hoặc cài skill cho host tương ứng
- Kiểm tra công cụ | Kiểm tra ffmpeg nếu bạn xử lý video
- Mở phiên agent mới | Để host nạp các skill vừa cài
```

### Chọn cách dùng

Nếu bạn đang dùng Claude Code, repo cung cấp plugin. Nếu dùng Codex hoặc Grok, bạn clone repo và chạy script cài skill. Các lệnh dưới đây là các lệnh README cung cấp.

### Cài cho Claude Code

Mở terminal tại thư mục bạn muốn cài plugin, rồi chạy:

```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"
```

Lệnh đầu thêm repo vào marketplace ở chế độ sparse. Theo README, chế độ này chỉ lấy manifest plugin và các skill, không lấy media showcase.

Lệnh thứ hai cài plugin `agent-sprite-forge`. Lệnh cuối cài ba thư viện Python cần cho plugin. Nếu terminal báo không tìm thấy `claude`, bạn đang dùng sai môi trường hoặc Claude Code chưa được cài; README của repo này không hướng dẫn cài Claude Code.

### Cài cho Codex

Clone repo rồi đi vào thư mục repo:

```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
```

`git clone` tải mã nguồn về máy. `cd agent-sprite-forge` đưa terminal vào đúng thư mục. `python -m pip install -r requirements.txt` cài các gói được khai báo trong file requirements của repo.

Lệnh cuối cài các skill cho Codex. README ghi `--apply` sẽ sao lưu bản đã cài và ghi manifest sha256. Nếu bạn đã từng cài bản khác, nên đọc thông báo sao lưu để biết vị trí bản cũ.

### Cài cho Grok hoặc host agents

Từ cùng thư mục clone, chạy lệnh tương ứng:

```bash
python tools/install_skills.py --apply --host grok
python tools/install_skills.py --apply --host agents
python tools/install_skills.py --apply --dest <folder>
```

`--host grok` ghi skill vào `~/.grok/skills`. `--host agents` ghi vào `~/.agents/skills`. Với `--dest <folder>`, bạn thay `<folder>` bằng thư mục skill muốn dùng.

Không chạy cả ba lệnh nếu bạn chỉ dùng một host. Hãy chọn đúng host để tránh cài nhiều bản không cần thiết.

### Kiểm tra thay đổi của skill

Sau này, bạn có thể kiểm tra bản đã cài có bị thay đổi hay không:

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

Nếu bạn cài cho Grok thì thay `codex` bằng `grok`. README ghi lệnh `--check` báo drift, tức khác biệt giữa bản đã cài và manifest.

### Kiểm tra ffmpeg và mở phiên mới

Nếu pipeline cần video, cài ffmpeg 5.1+ và bảo đảm lệnh `ffmpeg` nằm trên `PATH`. README không đưa lệnh cài ffmpeg cho từng hệ điều hành, nên bạn cần cài theo cách phù hợp với máy của mình.

Sau khi cài skill, hãy bắt đầu một phiên agent mới. README nói đây là bước cần thiết để skill được nạp. Nếu vẫn không thấy `$generate2dsprite` hoặc `$video2dsprite`, hãy kiểm tra host, thư mục cài và manifest trước khi chạy lại.

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

Cách kiểm tra thực tế là mở phiên agent mới và thử yêu cầu tạo master still:

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

Theo README, agent sẽ chạy quy trình `master_still.py generate --takes 3`, hiển thị các take, cho phép sửa near-miss bằng `master_still.py edit`, rồi duyệt một ảnh. Kết quả phải có master still và file `master.json` ghi nhận ảnh đã duyệt.

Nếu muốn kiểm tra tuyến animation, dùng prompt:

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

Màn hình hoặc log cần cho thấy agent nhận được skill và bắt đầu xử lý master đã duyệt. Nếu có video, hãy kiểm tra ffmpeg trên `PATH`. Nếu có đầu ra engine, kiểm tra PNG atlas, file animation và các file export có được tạo theo yêu cầu hay không.

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

### Chủ game indie cần một nhân vật hoàn chỉnh

Bạn là dev làm game 2D và mới chỉ có ý tưởng về nhân vật. Hãy dùng `$generate2dsprite` để mô tả nhân vật, hướng nhìn, độ phân giải và phong cách. Duyệt một master still trước, sau đó dùng `$video2dsprite` yêu cầu các hành động cần thiết.

Kết quả là một bộ animation có thể tiếp tục đóng gói cho Godot hoặc web. Bạn nên kiểm tra walk và run trước, vì đây là hai animation dễ lộ lỗi chân trượt hoặc tỷ lệ nhân vật thay đổi.

### Nhân viên văn phòng làm prototype game

Bạn không muốn tự học phần mềm pixel art ngay từ đầu nhưng cần một nhân vật mẫu cho bản demo. Hãy yêu cầu tạo master, sau đó chọn finish pixel hoặc hibit. Với hibit, mô tả nhân vật là flat lineless art để pipeline có đầu vào phù hợp.

Sau khi có sprite, bạn có thể dùng output PNG và animation package để trình bày prototype. Đây là cách nhanh để kiểm tra cảm giác chuyển động trước khi thuê họa sĩ hoàn thiện.

### Nhóm muốn giữ phong cách cho nhiều nhân vật

Bạn đã có một sprite tham chiếu và cần thêm pháp sư, hiệp sĩ xương hoặc rồng băng. Dùng `ask-cast` và `cast` để tạo nhân vật bên cạnh master. Sau đó chạy `lineup` để kiểm tra chiều cao và đường nền.

Cách này hữu ích khi nhóm muốn các nhân vật đứng cùng một scene mà không bị lệch kích thước pixel. Tuy vậy, vẫn nên duyệt từng nhân vật trước khi tạo toàn bộ animation.

### Dev Godot cần hiệu ứng hoặc map thử nghiệm

Bạn có thể chọn tuyến pixelfx cho hiệu ứng lửa, phép thuật, va chạm, thời tiết, vật phẩm hoặc UI. Nếu pixelfx đã được cài, chạy kiểm tra tuyến rồi render hiệu ứng. Nếu không, dùng tuyến ảnh và xử lý bằng `hibit_fx.py pixelize`.

Với map, hibit plate tạo background có bảng màu giới hạn và shade map. Sau đó bạn kiểm tra lại trong Godot hoặc công cụ map tương ứng, vì output của pipeline vẫn cần được tích hợp vào cấu trúc game cụ thể của bạn.

> Một master still được duyệt tốt có thể trở thành chuẩn cho cả nhân vật, animation và bộ xuất game.
>
> — Ông T

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

### Không tìm thấy lệnh `claude` hoặc skill

Có thể Claude Code chưa được cài, plugin chưa được cài hoặc bạn chưa mở phiên mới. Kiểm tra lại đúng host, chạy lại lệnh plugin tương ứng và bắt đầu một phiên agent mới.

### `pip` cài lỗi hoặc thiếu thư viện

Hãy chắc chắn terminal đang ở đúng thư mục clone khi chạy `python -m pip install -r requirements.txt`. Với Claude Code, kiểm tra bạn đã chạy đủ lệnh cài `numpy`, `Pillow` và `scipy` như README.

### Video không xử lý được

Nguyên nhân thường gặp là ffmpeg chưa có trên `PATH` hoặc phiên bản thấp hơn 5.1. Cài phiên bản phù hợp, mở terminal mới nếu cần, rồi kiểm tra lại trước khi chạy pipeline video.

### Không có API key hoặc agent không tạo được ảnh

API key là tùy chọn nhưng tuyến tạo ảnh cần một nhà cung cấp hoặc CLI đã đăng nhập. README ghi fallback là Codex CLI, Grok CLI, rồi code art. Hãy xem phần `Setting API keys` trong README; không tự đoán tên biến môi trường.

### Animation bị lệch chân hoặc màu thay đổi

Hãy bắt đầu lại từ một master still rõ ràng và duyệt kỹ ảnh gốc. Pipeline có bước đo chân, chọn loop, khóa màu và kiểm tra take, nhưng kết quả sinh ảnh vẫn cần được bạn xem lại trước khi đưa vào game.

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

Bạn nên dùng agent-sprite-forge nếu muốn biến prompt và một ảnh nhân vật thành prototype animation nhanh, đặc biệt khi đang dùng Claude Code, Codex hoặc Grok. Repo có nhiều bước xử lý thực tế, hỗ trợ Windows, có kiểm tra chất lượng, có pixel look, hibit, map, hiệu ứng và nhiều định dạng xuất.

Giấy phép MIT giúp repo dễ thử trong dự án cá nhân hoặc prototype. Repo cũng có khoảng 5663 sao và 550 fork, cho thấy có mức độ quan tâm đáng kể từ cộng đồng.

Giới hạn là pipeline phụ thuộc vào chất lượng ảnh và video đầu vào. API image-to-video có thể tốn phí hoặc cho kết quả không ổn định. Các bước kiểm tra giúp giảm lỗi nhưng không thay thế việc duyệt từng frame. README được cung cấp cũng không ghi chi tiết cách cấu hình từng nhà cung cấp API, nên phần này cần được đọc trực tiếp trong mục `Setting API keys` của repo.

Nếu bạn cần animation thương mại có chuyển động được duyệt thủ công ở từng frame, cần kiểm soát nghệ thuật tuyệt đối hoặc không muốn phụ thuộc model tạo ảnh, hãy cân nhắc Aseprite và quy trình vẽ tay. Nếu mục tiêu là dựng prototype nhanh, thử nhiều nhân vật và xuất sang nhiều engine, agent-sprite-forge là một lựa chọn đá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. Tuy nhiên, việc tạo ảnh hoặc video qua các nhà cung cấp API có thể phát sinh chi phí; README không nêu bảng giá.

### Có cần GPU không?

Tư liệu được cung cấp không nói rằng phải có GPU. README mô tả các tuyến dùng API, CLI đã đăng nhập hoặc code art, nhưng không nêu yêu cầu phần cứng cụ thể.

### Có chạy được trên Windows không?

Có dấu hiệu hỗ trợ Windows trong README, gồm xử lý thư mục sandbox của Codex, file bị khóa và console cp1252/cp950. Tuy vậy, repo không đưa hướng dẫn cài riêng cho từng phiên bản Windows.

### Có bắt buộc phải có API key không?

Không bắt buộc trong mọi trường hợp. Nếu không cấu hình key, agent có thể dùng Codex CLI hoặc Grok CLI đã đăng nhập; code art là phương án cuối theo README.

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

Chỉ cần khi xử lý video. README yêu cầu ffmpeg 5.1+ có trên PATH.

### Repo xuất được file cho Godot và Aseprite không?

Có. README nêu animation.json 3.0, PNG atlas, Godot SpriteFrames, Godot Sprite3D và Aseprite JSON cùng các đầu ra cho web game.

### Khác gì so với tự vẽ sprite trong Aseprite?

Repo tập trung vào việc tạo master still rồi sinh nhiều hành động, xử lý frame, khóa màu và đóng gói tự động. Aseprite phù hợp hơn nếu bạn cần kiểm soát thủ công từng pixel; README không đưa so sánh trực tiếp với Aseprite.
