agent-sprite-forge: tạo bộ sprite game từ prompt — 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 cho Claude Code, Codex và Grok, dùng để tạo sprite 2D, sprite sheet, animation, map và GIF từ prompt. Repo có quy trình tự động từ ảnh master đến file xuất cho game; cài đặt ở mức vừa phải vì cần Python, một số thư viện và tùy chọn API hoặc CLI đã đăng nhập.
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 dùng trong game. Bạn có thể tạo ảnh master, sinh các hành động như idle, walk, run, attack, jump và hurt, sau đó đóng gói cho Godot, Aseprite hoặc web game.
Repo phù hợp với nhà phát triển game 2D, người làm prototype nhanh, nhóm nhỏ không có họa sĩ chuyên về animation và người muốn thử quy trình tạo asset bằng AI. Điểm đáng giá nhất là bạn không phải tự cắt từng frame bằng tay: công cụ tự kiểm tra chuyển động, xử lý nền, chọn loop, điều chỉnh tốc độ và xuất dữ liệu animation.
Repo hiện có khoảng 5663 sao và 550 fork, dùng giấy phép MIT. Ngoài phong cách HD, repo còn có các quy trình pixel và hibit để tạo sprite có bảng màu, alpha rõ ràng và kích thước phù hợp với game.
0x0funky/agent-sprite-forge
Skill biến một ảnh nhân vật thành bộ sprite, animation, map và file xuất cho Godot, Aseprite hoặc web game.
I.Agent Sprite Forge làm được gì
A.Tạo ảnh master làm chuẩn cho cả nhân vật
Bạn bắt đầu bằng một ảnh nhân vật đã duyệt. Ảnh này giữ vai trò chuẩn về hình dáng, màu sắc, tỷ lệ và cách tạo dáng. Các hành động tiếp theo được sinh dựa trên master nên nhân vật ít bị thay đổi giữa các animation hơn so với việc tạo từng ảnh độc lập.
Skill có thể tạo nhiều take, cho bạn xem kết quả, sửa một điểm cụ thể rồi duyệt một ảnh. Ví dụ, bạn có thể yêu cầu chỉ đổi màu khăn, giữ nguyên mọi chi tiết khác. Kết quả được ghi vào master.json, giúp các bước sau dùng đúng nhân vật đã chọn.
B.Sinh cả bộ hành động từ một ảnh
Từ master, công cụ tạo một 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ộ. Quy trình này phù hợp khi bạn cần nhanh một nhân vật có đủ trạng thái để đưa vào prototype.
Mỗi take được kiểm tra nhiều yếu tố như 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 ảnh, nền, vật thể thừa, chuyển động, tư thế cuối, lem màu và thời lượng. Nếu take chưa đạt, skill có thể thêm điều kiện sửa rồi tạo lại.
C.Làm sạch frame và chọn loop
Các frame video được tách, xử lý nền bằng soft matte, đăng ký lại vị trí và chọn đoạn lặp dựa trên phép đo. Với animation một lần như attack, công cụ có thể bỏ phần đứng yên thừa và đưa đòn đánh về tốc độ phù hợp với game.
Điều này hữu ích khi video AI chạy quá chậm hoặc nhân vật bị trượt chân. Repo có quy trình đo tốc độ run từ chân chạm đất để hạn chế hiện tượng chân trượt trên mặt đất.
D.Xuất nhiều định dạng cho engine
Bộ kết quả có thể được đóng gói thành animation.json 3.0 cùng PNG atlas. Repo cũng hỗ trợ VP9-alpha WebM, packed-alpha MP4, Godot SpriteFrames, Godot Sprite3D và Aseprite JSON.
Nếu bạn làm map, repo có các hướng xuất cho Tiled, Godot và LDtk. Nhờ vậy, asset sau khi tạo không chỉ là một thư mục ảnh rời mà có thêm dữ liệu để đưa vào công cụ làm game.
E.Tạo pixel look và hibit
pixel_look.py có thể đọc lại lưới pixel của một hình tham chiếu, giữ tỷ lệ nhân vật, giảm màu và tạo sprite có alpha nhị phân. Quy trình này phù hợp khi bạn muốn nhân vật mới có cùng cảm giác pixel với một sprite mẫu.
Hibit đi theo hướng khác: yêu cầu mô hình tạo hình phẳng, ít sắc độ và không viền, rồi mới biến hình đó thành pixel art. Công cụ dùng palette học từ ảnh nguồn, downscale theo majority vote, giảm nhấp nháy, giữ mắt và điểm sáng, sau đó thêm viền theo màu của chính sprite.
F.Tạo hiệu ứng và nền
Với hiệu ứng hibit, repo hỗ trợ hai tuyến. Tuyến pixelfx dùng hiệu ứng pixel được tạo bằng code và chạy cục bộ. Tuyến image tạo một sheet 2x2 rồi xử lý thành pixel effect.
Repo cũng có hibit_plate.py để tạo nền 480x270, palette 14 màu, cùng bản đồ bóng để dùng cho ánh sáng và hiệu ứng đánh trúng mà không cần thêm màu mới.
G.Giữ màu và kiểm tra chất lượng
Video model có thể làm màu giày, tóc hoặc áo thay đổi giữa các frame. Repo có colour lock để giữ màu thiết kế theo master, đồng thời có bước QC để phát hiện các take không phù hợp.
Các công cụ Python trong repo đảm nhiệm việc key, register, loop, retime, finish và package. Nhờ đó, bạn có thể lặp lại cùng quy trình cho nhiều nhân vật thay vì xử lý thủ công từng bộ ảnh.
II.Cần chuẩn bị gì
Bạn cần một máy có Python và một terminal để clone repo, cài thư viện rồi chạy script. README cung cấp cách cài qua requirements.txt; các thư viện chính được thể hiện trong lệnh cài plugin là numpy, Pillow và scipy.
Repo có thể dùng với Claude Code, Codex hoặc Grok. Với Claude Code, bạn cài plugin từ marketplace. Với Codex và Grok, bạn clone repo rồi chạy script cài skill vào đúng thư mục của host.
Nếu muốn tạo video, máy cần có ffmpeg 5.1+ trong PATH. README cũng cho biết repo đã được làm cứng cho Windows, bao gồm việc xử lý thư mục chạy sandbox của Codex, file bị khóa và console dùng bảng mã cp1252 hoặc cp950.
Bạn có thể cấu hình API key cho OpenAI, Google Gemini, xAI, BytePlus hoặc fal.ai. Nếu không cấu hình key, agent dùng Codex CLI hoặc Grok CLI mà bạn đã đăng nhập. README chưa ghi chi tiết giá của từng nhà cung cấp, vì vậy chi phí còn phụ thuộc route và tài khoản bạn chọn.
Nếu dùng tuyến pixelfx, bạn cần cài riêng dự án pixelfx và Node 18+. README nói tuyến này chạy cục bộ và miễn phí về mặt render, nhưng việc cài pixelfx là bước riêng ngoài repo Agent Sprite Forge.
API key và quyền đăng nhập có thể quyết định route tạo ảnh hoặc video. Hãy kiểm tra tài khoản, giới hạn sử dụng và quyền truy cập trước khi chạy nhiều take. Nếu không cấu hình key, agent có thể dùng CLI đang đăng nhập trên máy.
III.Cài đặt từng bước
- Chọn hostXác định bạn dùng Claude Code, Codex hay Grok
- Cài repo và thư việnClone repo hoặc thêm plugin, sau đó cài dependency
- Cài skillĐưa skill vào Codex, Grok hoặc dùng trực tiếp trong Claude Code
- Kiểm tra công cụ phụBảo đảm ffmpeg có trong PATH nếu làm video
- Bắt đầu phiên mớiMở phiên agent mới để skill được nạp
A.Chọn cách cài theo công cụ bạn đang dùng
Nếu dùng Claude Code, bạn có thể cài marketplace và plugin bằng các lệnh dưới đây. Lệnh --sparse chỉ checkout manifest plugin và các skill, không lấy phần media showcase.
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"Nếu dùng Codex, mở terminal tại thư mục muốn chứa repo rồi clone. Sau đó đi vào đúng thư mục repo và cài các dependency trong file requirements.txt.
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 git clone tải mã nguồn về máy. cd agent-sprite-forge chuyển terminal vào repo. python -m pip install -r requirements.txt đọc danh sách gói mà repo khai báo. Lệnh cuối cài skill cho Codex.
Nếu Windows không nhận lệnh python, bạn cần dùng đúng cách gọi Python đang có trên máy theo cấu hình của mình. README không đưa một lệnh thay thế cụ thể, nên không nên tự đoán tên môi trường hoặc đường dẫn.
B.Cài skill cho Grok hoặc host khác
Bạn dùng lại bản clone ở bước trước, sau đó chạy lệnh tương ứng. Với Grok, skill được ghi vào ~/.grok/skills. Với host agents, README chỉ rõ thư mục đích mặc định là ~/.agents/skills.
python tools/install_skills.py --apply --host grok
python tools/install_skills.py --apply --host agents
python tools/install_skills.py --apply --host grok --dest <folder>--apply sao lưu bản đã cài và ghi manifest sha256. Sau này bạn có thể kiểm tra thay đổi bằng lệnh sau:
python tools/install_skills.py --check --host codexKhi dùng --dest <folder>, thay <folder> bằng thư mục skill mà host của bạn sử dụng. Không gõ nguyên dấu ngoặc nhọn nếu đó chỉ là ký hiệu đại diện. Sau khi cài xong, hãy bắt đầu một phiên agent mới để skill được nạp.
C.Kiểm tra ffmpeg nếu làm animation video
README yêu cầu ffmpeg 5.1+ nằm trong PATH khi xử lý video. Tư liệu được cung cấp chưa nêu lệnh kiểm tra phiên bản cụ thể, nên bạn hãy kiểm tra theo cách quản lý phần mềm của hệ điều hành và bảo đảm terminal gọi được ffmpeg trước khi chạy pipeline.
Nếu bạn chỉ muốn đọc hoặc xử lý asset tĩnh, phần yêu cầu ffmpeg có thể chưa xuất hiện ngay. Tuy vậy, các bước video2dsprite và tạo bộ hành động từ clip cần công cụ video theo yêu cầu của README.
D.Tạo ảnh master đầu tiên
Sau khi mở phiên agent mới, gọi skill generate2dsprite bằng prompt mô tả nhân vật. Prompt mẫu trong README là:
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 chạy quy trình master_still.py generate --takes 3, tạo ba take qua route_media.py, hiển thị để bạn chọn, rồi có thể sửa một take gần đúng bằng master_still.py edit. Hãy mô tả rõ góc nhìn, hướng nhân vật, quần áo, vũ khí và chất lượng mong muốn.
Khi duyệt xong, ảnh được key, đưa về khung chuẩn và ghi vào master.json. Đây là file quan trọng vì bước tạo animation phía sau sẽ dùng nó làm nguồn chuẩn.
E.Tạo bộ sprite từ master
Dùng skill video2dsprite với prompt mẫu sau:
Use $video2dsprite to animate the approved Aria master: idle, walk, run, attack, jump and hurt. Package them for Godot and the web.README cho biết script bên dưới nằm trong thư mục skill đã cài. Phần tài liệu được cung cấp chỉ hiển thị dòng mở đầu của lệnh:
python "<skill-dir>/scripts/sprite_set.py" plan --master art/aria-master/master.json -Thay <skill-dir> bằng thư mục video2dsprite thực tế trên máy. README đã cung cấp trong tư liệu bị cắt ở phần tiếp theo, nên mình không thêm các cờ hoặc lệnh chưa được nhìn thấy. Hãy xem tiếp phần Quickstart trong README để biết các lệnh còn lại của pipeline.
IV.Kiểm tra đã chạy được chưa
Với Codex hoặc Grok, dấu hiệu đầu tiên là lệnh install_skills.py --apply chạy xong và tạo bản cài skill. Bạn có thể dùng lệnh kiểm tra manifest để xem bản cài có bị thay đổi hay không:
python tools/install_skills.py --check --host codexNếu dùng host Grok, thay host tương ứng trong lệnh kiểm tra theo cách repo hướng dẫn. Sau đó bắt đầu phiên agent mới. Khi skill được nạp, agent nhận diện được các tên như $generate2dsprite và $video2dsprite trong prompt.
Khi tạo master thành công, agent phải hiển thị các take để bạn duyệt và tạo file master.json. Khi tạo bộ sprite thành công, pipeline tiếp tục từ master, tạo clip theo từng hành động, xử lý frame rồi đóng gói định dạng bạn yêu cầu.
Một kết quả hoàn chỉnh thường gồm PNG atlas, dữ liệu animation.json 3.0 và file xuất cho engine nếu bạn yêu cầu. Với Godot, hãy kiểm tra có SpriteFrames hoặc Sprite3D. Với web, kiểm tra atlas và dữ liệu animation. Với Aseprite, kiểm tra file JSON tương ứng.
V.Dùng vào việc thật
A.Chủ studio game nhỏ cần nhân vật prototype
Bạn có thể mô tả một nhân vật, tạo ba take master rồi chọn một take hợp nhất. Sau đó yêu cầu idle, walk, run, attack, jump và hurt, đồng thời bảo agent đóng gói cho Godot và web.
Use $generate2dsprite to make a master still of a small shopkeeper robot: round body, blue apron, orange cap, side view, facing right, HD.Kết quả mong đợi là một master được ghi nhận, sau đó một bộ hành động có thể đưa vào prototype thay vì phải chờ vẽ thủ công từng frame.
B.Dev mới học làm game 2D
Bạn có thể dùng pixel look khi muốn nhiều nhân vật có cùng kích thước, palette và cảm giác hình ảnh. Hãy chuẩn bị một sprite tham chiếu, mô tả nhân vật mới và để skill đọc lại lưới pixel thay vì chỉ yêu cầu mô hình “vẽ pixel art”.
Quy trình này hữu ích khi nhân vật ban đầu có màu và chi tiết không đều. Kết quả hướng tới sprite có alpha 0 hoặc 255, palette giới hạn và kích thước rõ ràng hơn.
C.Nhân viên văn phòng làm demo tương tác
Nếu bạn cần một animation đơn giản cho bản trình diễn, hãy yêu cầu một nhân vật có idle, walk và một hành động. Pipeline có thể xử lý clip, chọn loop và retime one-shot để chuyển động phù hợp với tốc độ trong demo.
Bạn không cần tự cắt từng frame, nhưng vẫn nên duyệt master và xem các take trước khi đóng gói. Nếu nhân vật bị đổi mặt, thừa vật thể hoặc lệch chân, hãy tạo lại take với điều kiện rõ hơn.
D.Nhóm làm game cần hiệu ứng pixel và map
Với phong cách hibit, bạn có thể dùng sprite_set.py --finish hibit cho nhân vật, sau đó tạo hiệu ứng bằng tuyến pixelfx hoặc image route. Pixelfx phù hợp khi muốn hiệu ứng chạy cục bộ; image route phù hợp khi muốn hiệu ứng theo phong cách và palette riêng của game.
Bạn cũng có thể dùng hibit_plate.py cho nền 480x270, sau đó đưa map sang Tiled, Godot hoặc LDtk theo khả năng xuất của repo.
Một ảnh master được duyệt tốt có thể trở thành nền móng cho cả bộ nhân vật nhất quán.
Ông T
VI.Lỗi hay gặp và cách xử lý
A.Skill đã cài nhưng agent không nhận diện
README yêu cầu bắt đầu một phiên agent mới sau khi cài. Hãy đóng phiên hiện tại, mở phiên mới rồi thử lại tên skill như $generate2dsprite. Với Codex hoặc Grok, kiểm tra bạn đã cài đúng host và đúng thư mục đích.
B.Cài dependency thất bại
Nguyên nhân thường là terminal đang ở sai thư mục hoặc Python không phải phiên bản bạn đang dùng để cài. Hãy chạy lệnh từ thư mục agent-sprite-forge, bảo đảm có requirements.txt, rồi dùng lại lệnh cài của README. Không tự thêm gói nếu chưa có trong tư liệu.
C.Pipeline video không chạy
Kiểm tra ffmpeg 5.1+ đã có trong PATH chưa. Nếu terminal không gọi được ffmpeg, cài hoặc cấu hình lại công cụ theo hệ điều hành rồi mở terminal mới trước khi thử lại.
D.Nhân vật bị lệch màu hoặc trượt chân
Đây là vấn đề dễ gặp với video tạo bằng AI. Hãy duyệt master rõ ràng, mô tả góc nhìn và tư thế, rồi để pipeline thực hiện colour lock, đăng ký frame và đo loop. Nếu take vẫn không đạt các điều kiện về chân, identity hoặc màu, hãy tạo lại take thay vì chỉnh tay hàng loạt.
E.Không biết route nào đang tạo ảnh
Agent ưu tiên API key đã cấu hình, sau đó dùng Codex hoặc Grok CLI đã đăng nhập, rồi mới dùng code art ở tuyến cuối. Kiểm tra key và trạng thái đăng nhập nếu kết quả không giống mong đợi. README chưa cung cấp bảng chi phí chi tiết cho từng provider, nên hãy kiểm tra tài khoản trước khi tạo nhiều take.
VII.Có nên dùng không
Nên dùng nếu bạn cần nhanh một bộ asset 2D có animation, muốn tự động hóa việc xử lý frame hoặc đang làm prototype cho Godot, Aseprite và web. Quy trình master-to-set giúp giữ nhân vật nhất quán hơn, còn các bước key, register, loop, retime và package giảm đáng kể công việc lặp.
Repo cũng đáng chú ý nếu bạn thích pixel art nhưng không muốn phụ thuộc hoàn toàn vào ảnh pixel do mô hình sinh ra. Pixel look và hibit cố gắng đưa hình ảnh về lưới, palette và alpha có thể kiểm soát được.
Giới hạn là chất lượng đầu ra vẫn phụ thuộc ảnh master, route tạo ảnh hoặc video, tài khoản API và khả năng kiểm tra của pipeline. Đây không phải công cụ thay thế hoàn toàn họa sĩ hoặc người làm animation; bạn vẫn cần duyệt take và sửa prompt. Việc cài nhiều host, ffmpeg và provider có thể gây khó cho người mới.
Nếu dự án cần phong cách nhân vật cố định tuyệt đối, timing animation thủ công hoặc asset thương mại đã được kiểm duyệt, bạn nên cân nhắc quy trình vẽ và animation truyền thống. Nếu mục tiêu là tạo nhanh prototype, thử nhiều ý tưởng hoặc đóng gói asset có cấu trúc cho engine, Agent Sprite Forge là lựa chọn đáng thử.
Câu hỏi thường gặp
Agent Sprite Forge là gì?
Đây là Agent Skill cho Claude Code, Codex và Grok, dùng để tạo sprite 2D, animation, map và các file xuất từ prompt. Quy trình bắt đầu từ một ảnh master rồi tạo các hành động cho nhân vật.
Repo có miễn phí không?
Repo dùng giấy phép MIT. Tuy nhiên README không nêu chi phí cụ thể của các API tạo ảnh hoặc video; chi phí có thể phụ thuộc provider và tài khoản bạn dùng.
Có cần GPU không?
Tư liệu được cung cấp không nói rằng phải có GPU. README nói công cụ có thể dùng API key, Codex hoặc Grok CLI đã đăng nhập, và có tuyến code art ở bước cuối.
Có chạy được trên Windows không?
Có. README cho biết repo đã được làm cứng cho Windows, gồm xử lý thư mục sandbox của Codex, file bị khóa và console cp1252 hoặc cp950.
Có cần ffmpeg không?
Video cần ffmpeg 5.1+ nằm trong PATH. Tư liệu không nói ffmpeg bắt buộc cho mọi thao tác ảnh tĩnh.
Dữ liệu và API key có an toàn không?
README cho biết bạn có thể cấu hình API key hoặc dùng CLI đã đăng nhập, nhưng không cung cấp chính sách lưu trữ hay bảo mật dữ liệu chi tiết. Bạn nên tự kiểm tra quyền truy cập và giới hạn tài khoản trước khi chạy.
Agent Sprite Forge khác gì việc tự cắt sprite sheet?
Repo tự động hóa nhiều bước từ ảnh master đến clip, key, register, chọn loop, retime, giữ màu và đóng gói. Bạn vẫn phải duyệt take và xử lý các trường hợp chất lượng không đạt.


