Universal Modder Tutorial

Use this workflow to take one small Terraria weapon from an idea to a build you can test in a practice world.

What you'll build

Start with one simple weapon using the tModLoader API. Choose an ordinary projectile and placeholder art so the first checkpoint is clear: the item loads, can be obtained, fires correctly and reports no relevant errors. Add custom behavior and artwork only after that works.

The Fal Arsenal example is a larger reference with five weapons, enemies and a boss, built for Terraria 1.4.4.9 on tModLoader 2026.07 under Windows. Read its Terraria field note and compare those versions with your install before reusing any code.

Before you start

Read what Universal Modder includes if the agent skills, um CLI and optional asset tools are new to you. This tutorial uses the agent for investigation and code changes, the CLI for supporting tasks, and fal only when you choose to generate assets.

1. Complete the Universal Modder installation checks in your chosen agent and terminal.
2. Have your own Terraria installation and tModLoader available. tModLoader is a free Steam app; add it to your library.
3. Choose an isolated practice world and a workspace for your source, MODDING_PLAN.md and MODLOG.md.

The plan states what you intend to do. The log records commands, changed paths, actual results and the next step. Keep those separate so an unrun command never becomes a claimed success.

Step 1: Pick a game and run um scan

In the intended tool environment:

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

Read the actual report. Look for the install path, engine, version, loader, save folders and suggested route. If several installations exist, identify the one you will use. If automatic discovery misses it, inspect um scan --help and give the actual path using the supported syntax.

Search results are starting points. Open the relevant note and compare its game version, platform and status. A note marked working applies to the versions it lists; game and loader updates can change the API, so match the note to your build.

Step 2: Let the agent investigate and write a plan

Use mod-any-game and game-recon for my Terraria installation.
Search the knowledge base, inspect the actual game and tModLoader versions,
and plan one simple weapon with placeholder art.
Write MODDING_PLAN.md with the chosen loader API, files to change,
backup locations, restore procedure and a precise in-game success check.
Keep unresolved version or path questions visible.

Review the plan before the agent changes the game. For this project, the tModLoader API is the natural starting route: its item and projectile classes expose the features needed for a small weapon. The game-recon skill shows how the agent reaches that decision.

Step 3: Back up your saves

Close the game and identify the real save folder from the scan and launcher configuration. Replace the placeholder with that folder:

um backup create "PATH_TO_TMODLOADER_SAVES" --name terraria-before-first-mod

Check the reported snapshot location and preserve it outside the files you will edit. Inspect the restore command before the first modded launch:

um backup restore --help

Write the snapshot name, source folder and restore command in MODLOG.md. When a recovery is actually needed, close the game and preserve any newer files you want to keep. For the snapshot name used above, preview the restore target and changes with:

um backup restore terraria-before-first-mod

Without --yes, this previews changes and exits without restoring files; there is no interactive confirmation prompt. Review the paths and changes first. Only when you are ready to restore that snapshot, run:

um backup restore terraria-before-first-mod --yes

The backup command reference also shows how to restore into a separate inspection directory. Avoid --clean unless you intend to remove files that are absent from the snapshot.

For extra isolation, give tModLoader its own save directory with the loader's -tmlsavedirectory option.

Step 4: Build one working slice

Ask the agent to create the smallest item and projectile implementation supported by your tModLoader version. Define a way to obtain the item in the practice world and a simple test target. Avoid adding a boss, procedural effects and custom art to the first build.

Implement only the planned item and a basic projectile using the installed
loader's API. Use placeholder art with the required dimensions.
Build it, preserve the real output, and stop at the first useful error.
List exactly how to obtain and test the item in the practice world.

To build the existing Fal Arsenal source, copy FalArsenal/ into tModLoader's ModSources directory and choose Workshop → Develop Mods → FalArsenal → Build + Reload. Your new mod will have its own name. Let tModLoader create the source folder and targets files before assuming their paths.

A completed build is the checkpoint for compilation. The next checkpoint is loading and using the item in the actual game. Keep the successful source state before making the next change.

Step 5: Add sprites, 3D or sound

Choose the asset dimensions and format from the game or loader before generating art. The Fal Arsenal example uses a 64 × 26 launcher sprite and a 38 × 16 missile sprite. Those sizes fit that example; your item's hitbox and draw code can need different values.

Inspect the item's required frame size, orientation and transparency.
Propose one sprite prompt and identify the chosen asset model's price.
After generation, remove the background, fit once with nearest-neighbor
scaling and preview it at the size the game will display.

The fal-assets skill covers model selection and the generation manifest. um sprite handles cutout, sizing and sheets; um render3d uses Blender when a 3D model must become directional frames. Use the CLI reference for full syntax and optional fal setup for credentials, or keep your own art for this first project.

A useful lesson from Fal Arsenal is orientation: its items point right and NPC sheets face left. Check the actual draw code before rotating an asset, especially for projectiles.

Step 6: Test the mod in the running game

Launch the practice profile, obtain the new item and exercise its behavior. Inspect tModLoader's client.log and take a screenshot that you actually review. Record the loaded mod version and the test world.

Check at least these outcomes:

• The correct item appears with the intended name and sprite.
• The projectile starts in the right place and moves in the intended direction.
• Damage, lifetime and collision match the small feature you planned.
• Repeating the action does not create obvious errors or leave broken state.
• Closing and reopening the practice session keeps the setup understandable.

A title screen or a loaded-mod list cannot show that a weapon behaves correctly. If the same failure repeats, preserve what you have observed and change the diagnosis before adding more features. The mod-any-game skill emphasizes in-game evidence for exactly this reason.

Step 7: Package it and run the publish check

Prepare a clean output directory containing your mod, installation instructions, dependencies, version requirements and credits. Then inspect it:

um publish check "PATH_TO_MOD_PACKAGE" --game "PATH_TO_GAME_INSTALL"

Replace both placeholders with your actual paths. Review every finding, including potential game files, decompiled source and secrets. The check is a useful filter, and you still review licenses and package contents. See the sharing rules.

State which checks you ran and which remain untested. Fal Arsenal, for example, leaves multiplayer unverified. Publishing is a separate decision after the package is ready for review.

Step 8: Record a demonstration and a field note

Set up a short repeatable scene showing the feature, then inspect the recording before sharing it. um win record and um video provide Windows capture and editing workflows; review their help for your capture environment. Ask before letting an agent take over keyboard or mouse input.

Turn the useful parts of MODLOG.md into a field note: versions, route, verification, failed approaches and fixes. Check um kb new --help and um kb check --help before preparing a contribution. Review any public post or pull request before submitting it.

In Fal Arsenal, external window capture proved preferable to the original in-game recorder. That is the kind of concrete lesson worth recording for someone who repeats the project.

When things go wrong

For recovery, move only your experiment's package out of the active mod folder after the game is closed. Keep shared dependencies and your source. Restore important saves from the pre-change snapshot using their original environment; opening a modded save without its content can itself change that save.

What to try next

Adapt the game-modding prompts, compare the three examples, or check the game support FAQ before choosing a different engine. The Minecraft page retains a separate fixed-version Fabric exercise for readers who want to inspect that route.