Agent Sprite Forge: tạo bộ sprite game 2D từ một ảnh gốc — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về 0x0funky/agent-sprite-forge — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: agent-sprite-forge: tạo sprite game từ prompt — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
Agent Sprite Forge là bộ Agent Skill giúp tạo sprite sheet 2D, khung PNG trong suốt, GIF động 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, nhảy…) rồi đóng gói cho engine game. Cài không quá khó nếu bạn đã quen dùng Claude Code hoặc Codex, vì chỉ cần vài lệnh và Python.
Agent Sprite Forge là bộ Agent Skill (kỹ năng cho trợ lý AI lập trình) dùng để làm sprite game 2D. Nó chạy bên trong Claude Code (dạng plugin), Codex và Grok. Bạn nhờ agent vẽ một ảnh gốc của nhân vật, bạn duyệt ảnh đó, rồi agent tạo ra mọi hành động của nhân vật: đứng yên, đi, chạy, đánh, nhảy, bị trúng đòn. Mỗi hành động được xử lý xong và xuất sẵn cho Godot, Aseprite hoặc game chạy trên web.
Vấn đề repo giải quyết rất thực tế. Muốn có một nhân vật game đủ động tác, bạn thường phải vẽ từng khung hình hoặc cắt tay từ ảnh AI. Cách đó tốn công, nền hay bị viền màu lạ, bước chân trượt khi nhân vật chạy. Repo này tự động hoá phần việc nặng, còn bạn chỉ cần quyết định nhân vật trông thế nào.
Repo hợp với người làm game indie, người muốn thử làm game nhỏ để học, hoặc dân văn phòng muốn có nhân vật hoạt hình cho bài thuyết trình. Điểm đáng giá nhất là các bước xử lý được viết bằng mã Python chạy cố định: tách nền, căn khung, chọn đoạn lặp, chỉnh tốc độ, đóng gói. Vì vậy kết quả đo đạc được, không chỉ "trông cũng được". Repo hiện có khoảng 5561 sao và 537 fork, giấy phép MIT.
0x0funky/agent-sprite-forge
Bộ skill cho Claude Code, Codex và Grok: duyệt một ảnh nhân vật, nhận đủ các hành động đã tách nền, lặp mượt, xuất cho Godot, Aseprite hoặc web game.
I.Agent Sprite Forge làm được gì
Từ một ảnh gốc ra cả bộ hành động. Bạn duyệt một ảnh nhân vật (gọi là master still). Với mỗi hành động, agent tạo một đoạn video ngắn từ ảnh đó, rồi biến đoạn video thành các khung sprite. Nhờ vậy nhân vật giữ nguyên diện mạo ở mọi hành động.
Tách nền mềm, không viền tím. Bộ tách nền (keyer) giúp mép nhân vật sạch. README đo trên một đoạn clip thật: viền màu thừa giảm từ 0.704 xuống 0, và thời gian xử lý 145 khung giảm từ 271 giây xuống 44 giây.
Chỉnh đòn đánh về tốc độ game. Video AI hay diễn một cú đánh nhanh thành cảnh quay chậm. Công cụ cắt các đoạn đứng hình và ghim điểm trúng đòn: README ghi một cú đánh từ 4,1 giây còn 0,7 giây.
Khoá màu (colour lock). Video AI hay làm lệch màu ở tay chân đang chuyển động. Khoá màu giữ các màu thiết kế bám theo ảnh gốc, nên nhân vật ít nhấp nháy màu hơn.
Hai kiểu hoàn thiện. Mặc định là bản HD. Khi bạn yêu cầu, có thể làm bản pixel gọn: tối đa 32 màu, viền chọn lọc, độ trong suốt chỉ có hai mức. Ngoài ra có kiểu hibit (nhờ AI vẽ ảnh phẳng không viền rồi tự tạo pixel sau) và pixel looks (cả đội nhân vật bám theo một sprite mẫu bạn thích).
Kiểm tra chất lượng tự động. Mỗi lần tạo clip đều qua các cổng kiểm tra như diện tích, bàn chân, nhận dạng nhân vật, nền, vật thể thừa. Clip lỗi sẽ được tạo lại.
Xuất cho nhiều nơi. Gói animation.json 3.0 kèm atlas PNG, WebM nền trong suốt, MP4, SpriteFrames và Sprite3D cho Godot, JSON cho Aseprite, bản đồ cho Tiled, Godot và LDtk.
II.Cần chuẩn bị gì
- Một trong ba môi trường agent: Claude Code, Codex hoặc Grok.
- Python và pip. README yêu cầu gói numpy từ 1.26, Pillow từ 10.1, scipy từ 1.11. README không ghi rõ phiên bản Python tối thiểu trong phần mình có.
- ffmpeg 5.1 trở lên nằm trong
PATHnếu bạn làm phần video. - Nguồn tạo ảnh và video. Hoặc bạn cấu hình API key (OpenAI, Google Gemini, xAI, BytePlus, fal.ai), hoặc dùng Codex CLI / Grok CLI đã đăng nhập. Không có cả hai thì repo dùng "code art" làm phương án cuối.
- Windows: README cho biết repo đã được xử lý riêng cho Windows (thư mục chạy trong sandbox Codex, dọn file bị khoá, console cp1252/cp950).
- Muốn dùng hiệu ứng pixelfx (tuỳ chọn) thì cần thêm Node 18 trở lên.
- README không nói gì về yêu cầu GPU hay RAM.
Tạo ảnh và video qua API key có thể tính phí theo nhà cung cấp bạn chọn. Đừng dán key vào tin nhắn chat hay đưa lên GitHub. Nếu chưa muốn tốn phí API, bạn có thể thử dùng Codex hoặc Grok CLI đã đăng nhập, nhưng hạn mức phụ thuộc gói của bạn. README chưa có thông tin chi tiết về mức phí.
III.Cài đặt từng bước
- Chọn môi trườngClaude Code (plugin), Codex hoặc Grok
- Cài skillChạy lệnh tương ứng với môi trường của bạn
- Cài thư viện Pythonnumpy, Pillow, scipy (hoặc requirements.txt)
- Cài ffmpegBản 5.1 trở lên, nằm trong PATH, nếu làm video
- Mở phiên agent mớiĐể skill được nạp
A.Cách A: cài cho Claude Code (plugin)
Mở terminal bất kỳ (trên Windows là PowerShell), chạy lần lượt ba lệnh. Hai lệnh đầu thêm kho plugin rồi cài plugin. Lệnh thứ ba cài thư viện Python.
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 và skill, không tải ảnh minh hoạ nặng. Chỗ người mới hay vấp là dấu nháy kép quanh tên gói. Hãy giữ nguyên, nếu không terminal có thể hiểu >= là chuyển hướng ghi file.
B.Cách B: cài cho Codex
Cách này tải toàn bộ repo về máy, nên bạn cần có git. Lệnh cd để vào thư mục vừa tải trước khi chạy các lệnh sau.
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 codexLệnh cuối chép skill vào thư mục skill của Codex. Cờ --apply sẽ sao lưu bản đã cài trước đó và ghi một file manifest sha256.
C.Cách C: cài cho Grok
Từ chính thư mục repo đã clone ở cách B (đã cd vào và đã cài requirements), chạy:
python tools/install_skills.py --apply --host grokREADME cho biết lệnh này ghi vào ~/.grok/skills. Nếu bạn muốn dùng thư mục chung, --host agents ghi vào ~/.agents/skills, còn --dest <thư mục> ghi vào thư mục skill bất kỳ.
D.Cài ffmpeg và mở phiên mới
Phần làm video cần ffmpeg 5.1 trở lên có trong PATH. README không kèm lệnh cài ffmpeg, bạn cài theo hướng dẫn chính thức của ffmpeg cho hệ điều hành của mình. Sau khi cài xong, hãy mở một phiên agent mới để skill được nạp. Đây là chỗ nhiều người bỏ sót.
Khoá API là tuỳ chọn. README có mục "Setting API keys" ở phần sau của tài liệu. Phần README mình có đã bị cắt trước mục này, nên bạn hãy mở file README.md trong repo và tìm đúng mục đó để biết tên biến cần điền.
IV.Kiểm tra đã chạy được chưa
Với Codex hoặc Grok, README có lệnh kiểm tra xem skill đã cài đúng và có bị sửa lệch không:
python tools/install_skills.py --check --host codexThay codex bằng grok hoặc agents nếu bạn cài ở đó. README mô tả lệnh này dùng để báo "drift", tức là bản đã cài khác với bản trong repo.
Cách thử thực tế hơn là mở phiên mới và gõ câu lệnh làm master still ở phần dưới. Nếu agent nhận ra $generate2dsprite và bắt đầu tạo vài ảnh thử cho bạn chọn, tức là skill đã được nạp. Nếu agent trả lời như chưa nghe tên skill, xem phần lỗi bên dưới.
V.Dùng vào việc thật
A.Dev indie cần một nhân vật chính có đủ động tác
Bạn đang làm game platformer bằng Godot và chưa có hoạ sĩ. Bước đầu là tạo ảnh gốc. Gõ câu này vào agent (câu mẫu nguyên văn từ README):
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.Agent tạo ba bản thử, đưa bạn xem, sửa bản gần đúng nếu cần và chốt một ảnh. Ảnh được tách nền, căn khung và ghi vào file master.json. Sau khi duyệt, bạn nhờ làm cả bộ:
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ả là sáu hành động đã tách nền, lặp mượt, đóng gói cho Godot và web.
Bạn chỉ cần duyệt đúng một ảnh, phần còn lại là việc của công cụ.
Ông T
B.Chủ shop muốn linh vật hoạt hình cho trang bán hàng
Bạn không làm game nhưng muốn một linh vật cho thương hiệu, có động tác vẫy tay, đi và nhảy. Bạn mô tả linh vật bằng lời, duyệt ảnh gốc, rồi xin các hành động mong muốn. README nói công cụ xuất được WebM nền trong suốt, MP4 và PNG trong suốt, nên bạn có thể đặt lên website mà không phải xoá nền thủ công. Hãy nói rõ với agent định dạng bạn cần (ví dụ "xuất WebM nền trong suốt"), vì mặc định README hướng về gói cho engine game.
C.Người thích pixel art muốn cả đội nhân vật cùng một phong cách
Bạn có một sprite pixel ưng ý và muốn thêm pháp sư, hiệp sĩ xương, rồng băng cho cùng phong cách. README giới thiệu chế độ pixel looks: sprite bạn thích làm mẫu, các nhân vật khác được vẽ cạnh mẫu để giữ cùng kích thước điểm ảnh và chiều cao. README ví dụ ba nhân vật cho ra 48 màu mỗi nhân vật, không có điểm ảnh mờ. Bạn chỉ cần nói với agent rằng muốn dùng pixel looks và đưa sprite mẫu. Chi tiết quy trình nằm ở file references/pixel-looks.md trong repo.
D.Làm nền và hiệu ứng cho một màn game nhỏ
Bộ skill còn có phần làm bản đồ và nền (generate2dmap), xuất cho Tiled, Godot, LDtk. Với kiểu hibit, README nói có thể tạo nền 480x270 bảng 14 màu. Hiệu ứng như lửa, tia sáng, va chạm có thể dùng thư viện pixelfx (dự án MIT riêng, cần Node 18+) hoặc đi đường tạo bằng ảnh. Nếu mới bắt đầu, bạn nên làm xong nhân vật trước, rồi hãy thêm nền và hiệu ứng.
VI.Lỗi hay gặp và cách xử lý
Agent không nhận ra skill. Nguyên nhân phổ biến nhất là chưa mở phiên agent mới sau khi cài. Hãy thoát và mở lại. Với Codex hoặc Grok, chạy lệnh --check ở trên để xem skill đã nằm đúng thư mục chưa. Nếu bạn cài vào --dest tuỳ chọn, hãy chắc agent của bạn đọc thư mục đó.
Lệnh python hoặc pip không chạy. Trên một số máy lệnh có tên khác hoặc Python chưa nằm trong PATH. Kiểm tra bằng cách mở terminal mới và gõ python --version. Đừng đổi sang tên lệnh khác nếu không chắc, hãy sửa PATH hoặc cài lại Python theo hướng dẫn chính thức.
Thiếu ffmpeg khi làm video. README yêu cầu bản 5.1 trở lên trong PATH. Nếu bước tạo clip hoặc xuất WebM/MP4 báo lỗi, hãy mở terminal và gõ ffmpeg -version để xem máy có nhận không. Chưa nhận thì cài lại và mở terminal mới.
Không tạo được ảnh hoặc video. Repo dùng API key bạn cấu hình, nếu không có thì dùng Codex hoặc Grok CLI đã đăng nhập. Nếu cả hai đều chưa sẵn sàng, bạn sẽ chỉ có phương án code art. Hãy đăng nhập CLI hoặc cấu hình key theo mục "Setting API keys" trong README.
Clip bị loại, phải tạo lại nhiều lần. Các cổng kiểm tra chất lượng có thể từ chối clip lệch nhân vật, lệch nền hoặc có vật thừa. Đây là hành vi thiết kế, không phải lỗi. Mỗi lần tạo lại thường tốn thêm lượt gọi dịch vụ, nên hãy mô tả nhân vật rõ ràng, dùng một góc nhìn nhất quán và theo dõi chi phí.
VII.Có nên dùng không
Điểm mạnh. Quy trình trọn gói từ ảnh gốc đến file cho engine, kèm số đo rõ ràng. Hỗ trợ Claude Code, Codex và Grok. Giấy phép MIT. Repo còn được cập nhật trong vài tháng gần đây. Có các kiểu hoàn thiện khác nhau cho cả HD lẫn pixel.
Giới hạn. Công cụ không tự vẽ miễn phí. Chất lượng và chi phí phụ thuộc vào dịch vụ tạo ảnh, tạo video bạn nối vào. Cần quen terminal, Python và agent AI. Cần ffmpeg cho video. Repo cũng có nhiều chế độ (HD, pixel, hibit, pixel looks), nên người mới nên bắt đầu với bản HD mặc định. README có file validation ghi cả điểm yếu, bạn nên đọc để có kỳ vọng thực tế.
Khi nào chọn cách khác. Nếu bạn chỉ cần vài icon tĩnh, một công cụ vẽ ảnh thông thường là đủ. Nếu bạn cần pixel art vẽ tay chuẩn chỉnh từng điểm ảnh cho game thương mại, hoạ sĩ hoặc Aseprite vẫn là lựa chọn kiểm soát tốt nhất. Với người muốn nhanh có một bộ sprite dùng thử, Agent Sprite Forge là một khởi đầu đáng thử.
Câu hỏi thường gặp
Agent Sprite Forge có miễn phí không?
Bản thân repo dùng giấy phép MIT nên dùng miễn phí. Tuy nhiên việc tạo ảnh và video đi qua dịch vụ bạn nối vào: API key (OpenAI, Gemini, xAI, BytePlus, fal.ai) hoặc Codex/Grok CLI đã đăng nhập. Chi phí phụ thuộc vào các dịch vụ đó, README phần mình có chưa nêu mức phí cụ thể.
Có cần GPU không?
README phần mình có không yêu cầu GPU. Ảnh và video do dịch vụ bạn chọn tạo ra, còn các bước xử lý bằng Python (tách nền, căn khung, đóng gói) chạy trên máy bạn. Chưa có thông tin về cấu hình máy tối thiểu.
Chạy trên Windows được không?
Được. README ghi repo đã được xử lý riêng cho Windows, gồm thư mục chạy trong sandbox Codex, dọn file bị khoá và console cp1252/cp950. Bạn vẫn cần cài Python, các thư viện và ffmpeg 5.1 trở lên.
Cần những gì để cài?
Cần Claude Code, Codex hoặc Grok, Python với numpy, Pillow, scipy, và ffmpeg 5.1+ nếu làm video. README còn nói bạn có thể cấu hình API key, hoặc dùng Codex/Grok CLI đã đăng nhập. Node 18+ chỉ cần nếu muốn dùng thư viện hiệu ứng pixelfx.
Xuất ra được những định dạng nào?
README liệt kê animation.json 3.0 kèm atlas PNG, WebM nền trong suốt, MP4, SpriteFrames và Sprite3D của Godot, JSON của Aseprite. Phần bản đồ hỗ trợ Tiled, Godot và LDtk. Ngoài ra repo mô tả khung PNG trong suốt và GIF động trong mô tả của tác giả.
Dữ liệu và ảnh của tôi có an toàn không?
Chưa có thông tin chi tiết về chính sách dữ liệu trong phần README mình có. Vì ảnh và video được tạo qua dịch vụ bạn chọn (API hoặc CLI đã đăng nhập), nội dung sẽ đi theo chính sách của dịch vụ đó. Bạn nên đọc điều khoản của nhà cung cấp trước khi gửi ảnh nhạy cảm.
Khác gì việc nhờ AI vẽ sprite sheet rồi tự cắt?
Theo README, trước bản 0.4 việc làm hoạt hình là cắt khung từ sprite sheet do AI vẽ hoặc tự tách nền một clip. Bản này tạo một clip cho mỗi hành động từ cùng một ảnh gốc rồi xử lý bằng mã đo đạc được. README đưa số liệu so sánh như số màu mỗi khung, viền thừa và thời gian xử lý.


