Panduan Universal Modder

Universal Modder adalah kumpulan alat sumber terbuka yang membantu agen pemrograman AI meneliti, membuat, dan menguji mod game PC. Isinya mencakup keterampilan agen, CLI Python bernama um, catatan untuk game tertentu, serta integrasi fal untuk membuat aset. Proyek aslinya adalah rehan-remade/universal-modder di GitHub (bahasa Inggris).

Mulailah dengan perubahan kecil pada game yang Anda miliki: kenali mesin game dan loader mod, lindungi berkas simpanan uji, buat fungsi dengan gambar sementara, lalu periksa di dalam game. Nama “Universal” menggambarkan pendekatan yang luas, bukan jaminan kompatibilitas dengan semua game dan versi.

Sumber diperiksa pada 9 Oktober 2026 berdasarkan commit 8370faa dan versi paket 0.2.0. Panduan ini mengacu pada dokumentasi dan kode sumber. Kami tidak menjalankan mod contoh atau menguji seluruh alur melalui OmniaKey. Sumber eksternal tersedia dalam bahasa Inggris.

Apa saja yang disediakan?

README proyek membedakan beberapa komponen:

Repositori mencantumkan cara pemasangan untuk Claude Code, Codex, Cursor, Gemini CLI, Copilot, dan OpenCode. Itu adalah jalur integrasi agen, bukan jaminan bahwa semua operasi game berjalan di setiap sistem operasi. Alat pengendali game Windows ditujukan untuk Windows secara langsung atau melalui WSL.

Cara memasang di Claude Code

README mencantumkan Git, Python 3.10 atau lebih baru, serta ffmpeg sebagai prasyarat dan menyarankan uv. Blender diperlukan untuk merender model 3D menjadi sprite. Siapkan alat sesuai alur kerja yang dipilih.

Masukkan dua perintah ini di dalam Claude Code:

/plugin marketplace add rehan-remade/universal-modder
/plugin install universal-modder@universal-modder

Ini adalah perintah plugin Claude Code, bukan perintah shell. Periksa kode dan izin yang diminta sebelum mengaktifkannya. Untuk agen lain, ikuti bagian yang sesuai dalam README asli.

Proyek menyediakan peluncur CLI untuk penggunaan melalui plugin dan repositori yang diklon. Jika terminal terpisah tidak menemukan um, pemasangan mandiri yang didokumentasikan adalah:

uv tool install git+https://github.com/rehan-remade/universal-modder
um --help

Langkah ini memasang CLI dari repositori. Langkah tersebut tidak otomatis mengatur agen atau akun fal. Perintah telah dicocokkan dengan sumber, tetapi tidak dijalankan untuk artikel ini.

Periksa game sebelum mengubah berkas

Ganti Terraria dengan nama game atau folder instalasinya:

um scan --list
um kb search "Terraria"
um scan "Terraria" --json

Menurut panduan pemeriksaan game, pemindai membaca berkas untuk melaporkan petunjuk mesin game, loader terpasang, lokasi simpanan, dan jalur pengerjaan. Jika game tidak ada di daftar koleksi, berikan foldernya secara langsung.

Hasil pemindaian merupakan bahan perencanaan, bukan bukti keamanan atau dukungan. Perangkat perlindungan bisa berada di luar folder game, dan peluncur bisa membuat identifikasi mesin keliru. Periksa juga dokumentasi terbaru loader komunitas dan kebijakan mod game tersebut.

Minta agen mencatat versi game dan loader, lokasi simpanan dan log, perubahan yang direncanakan, serta cara pemulihan di MODDING_PLAN.md. Simpan perkembangan pekerjaan di MODLOG.md. Utamakan loader yang sudah tersedia atau antarmuka mod resmi jika dapat mewujudkan ide Anda.

Permintaan pertama dengan hasil yang bisa diuji

Pilih fitur kecil yang hasilnya terlihat. Contoh berikut adalah templat permintaan dari kami, bukan mod yang telah diuji:

Dalam lingkungan uji Terraria lokal saya, rencanakan satu item dekoratif baru untuk versi tModLoader yang terpasang. Periksa game dan loader terlebih dahulu. Gunakan gambar sementara dan dunia uji yang boleh dibuang. Sebelum mengubah berkas, jelaskan jalur yang terdampak serta langkah pencadangan dan pemulihan. Tunjukkan cara memperoleh item, memeriksanya di game, dan menghapus mod. Minta persetujuan sebelum membuat aset berbayar atau menerbitkan apa pun.

Alur utama proyek menyarankan satu fungsi kecil yang bekerja dengan aset sementara sebelum menambah cakupan. Jadikan ini lima pemeriksaan:

1. Termuat: game berjalan dengan loader yang diinginkan dan log mengenali mod.
2. Terlihat: item atau perubahan muncul dalam adegan uji yang ditentukan.
3. Berfungsi: perilakunya sesuai permintaan, bukan sekadar berhasil dikompilasi.
4. Tersimpan: menyimpan dan memuat ulang dunia uji memberikan hasil yang diharapkan.
5. Dapat dipulihkan: menonaktifkan mod dan memulihkan cadangan mengembalikan kondisi yang diharapkan.

Setelah itu, barulah kerjakan sprite akhir, suara, atau video demonstrasi. Gambar hasil generasi atau build yang berhasil saja tidak membuktikan kompatibilitas di dalam game.

Game apa yang memiliki contoh?

Gunakan contoh sebagai titik awal dengan batas versi tertentu. Pengujian yang dilaporkan pembuatnya tidak menggantikan pemeriksaan pada komputer Anda.

• Terraria / tModLoader: Fal Arsenal berasal dari proyek pemain tunggal pada Terraria 1.4.4 dan tModLoader 2026.07. README menyebutkan bahwa multiplayer belum diuji. Gunakan dunia terpisah.
• Age of Empires II DE: contoh peradaban mencakup pembuatan gambar dan konversi sprite. Contoh tersebut menggantikan slot peradaban yang sudah ada, bukan membuktikan bahwa slot baru bisa ditambahkan tanpa batas.
• Minecraft × GTA V: menggabungkan dua game yang sedang berjalan dalam mode cerita GTA V. Target uji yang dicatat adalah GTA V Legacy di Steam, build 3889. Jangan perluas klaim ini ke GTA Online atau edisi lain.

Periksa buktinya secara berurutan: panduan mesin → contoh game beserta versinya → pengujian Anda di dalam game. Panduan Unity atau Unreal tidak menjadi sertifikat untuk setiap game yang memakai mesin itu.

Apakah gratis dan harus memakai fal?

Kode sumber alat menggunakan lisensi MIT. Namun, proyek lengkap bisa memiliki tiga kelompok biaya: akses model pemrograman, pembuatan aset, serta perangkat keras atau alat lokal untuk build dan pengujian.

fal memiliki harga model tersendiri yang bergantung pada model dan pengaturan. Dokumentasi autentikasinya memakai FAL_KEY. Atur kunci asli secara privat dalam lingkungan yang menjalankan agen. Nilai di bawah ini hanya pengganti sementara.

Untuk Bash atau Zsh:

export FAL_KEY="YOUR_FAL_API_KEY"

Untuk Windows PowerShell:

$env:FAL_KEY = "YOUR_FAL_API_KEY"

Kredensial model pemrograman, termasuk kunci OmniaKey, bukan kunci fal. Memasang plugin tidak menggabungkan tagihan kedua layanan. Sebelum menyetujui pembuatan banyak aset, periksa model dan jumlah generasinya. Jangan simpan kunci dalam berkas mod atau arsip publik.

Anda bisa memakai gambar sementara atau buatan sendiri. Panduan aset juga mendokumentasikan um comfy untuk membuat gambar melalui server ComfyUI lokal tanpa kunci fal. Resep gambar bawaannya tidak menggantikan seluruh alur audio, 3D, dan video fal. Perangkat keras dan model lokal tetap perlu disiapkan.

Jika percobaan pertama gagal

Ubah satu lapisan setiap kali:

• um tidak ditemukan: periksa PATH terminal dan pemasangan CLI mandiri sebelum menelusuri loader game.
• Game tidak terdeteksi: berikan folder instalasi dan bandingkan hasil dengan dokumentasi komunitas terbaru.
• Autentikasi fal gagal: pastikan proses agen menerima FAL_KEY untuk akun yang benar. Login agen yang berhasil tidak membuktikan autentikasi fal.
• Build berhasil tetapi mod tidak termuat: periksa versi, jalur instalasi, dan log loader sebelum membuat aset lagi.
• Gambar tampak salah: periksa ukuran, transparansi, susunan frame, dan arah sesuai kebutuhan game sebelum mengubah prompt gambar.

Simpan log kegagalan dan langkah reproduksi paling sederhana di catatan proyek. Upaya berikutnya akan memiliki sesuatu yang jelas untuk diuji.

Penggunaan online dan publikasi

Ikuti batas penggunaan proyek: game yang Anda miliki, pengujian offline atau lingkungan yang diizinkan dan Anda kendalikan, tanpa melewati anticheat, DRM, atau pemeriksaan kepemilikan. Proyek menolak injeksi ke klien online yang dilindungi. Server pribadi tidak otomatis menghapus perlindungan klien atau batasan penerbit.

Sebelum berbagi, tinjau ketentuan game serta lisensi aset dan alat. Lisensi MIT pada kit tidak memberi hak untuk membagikan berkas game, aset hasil ekstraksi, atau kode hasil dekompilasi. Bagikan karya Anda sendiri beserta petunjuk instalasi, versi yang diuji, dan cara menghapusnya.

Untuk sisi model, baca panduan koneksi Claude Code dan harga OmniaKey saat ini. Atur koneksi tersebut secara terpisah dari fal, lalu validasi alur mod yang sebenarnya di lingkungan Anda.