ThisCalculator

Everyday

Add Custom Items to a Starbound Server: Full Guide

Updated · Standard formula, shown below

This guide explains how to add custom items to a Starbound server, allowing you and your players to use unique weapons, armor, and objects that aren’t in the base game. You’ll learn how to create or install item mods, configure the server to load them, and verify everything works. Before starting, you’ll need access to the server’s file system (either locally or via FTP), a text editor, and basic familiarity with Starbound’s folder structure.

What You’ll Need

  • Starbound server files (either a dedicated server or the server files included with the game)
  • File access to the server (local directory, FTP, or hosting panel)
  • A text editor (Notepad++, VS Code, or even Notepad)
  • The custom item files you want to add (either downloaded from a mod site or created yourself)
  • Optional: a mod manager like Starbound Mod Manager (for local testing)

Step-by-Step

  1. Locate your server’s mod folder. The default path is Starbound/mods/ inside the server directory. If you’re using a hosting service, check their documentation for the mod folder location.
  2. Prepare the custom item files. Custom items are usually distributed as a .pak file (compiled mod) or as a folder with .json and .png files. If you have a folder, you can either keep it as a loose folder or pack it into a .pak using the Starbound asset packer. For simplicity, most server admins use .pak files.
  3. Copy the item files into the mods folder. Place the .pak file (or the folder) into the mods directory. If you have multiple mods, each should be in its own subfolder or as a separate .pak file.
  4. Verify the mod structure (if using loose files). If you’re adding a folder-based mod, ensure it has the correct structure: mods/MyMod/items/active/weapons/melee/sword/myweapon.sword etc. The .json files define the item properties, and the .png files are the icons and in-world textures.
  5. Edit the server configuration (if needed). Some mods require enabling in the starbound.config file. Open it and look for the assetSources or mods array. Add the mod’s folder name (e.g., "mods/MyMod") to the list. For .pak files, this is usually not necessary as they are auto-loaded.
  6. Restart the server. After adding the files, restart the Starbound server. The server will load the mods during startup. Watch the console output for any errors related to your mod.
  7. Test the item in-game. Connect to the server as an admin and use the command /spawnitem myitemname (replace with the actual item ID) to spawn the item. If it appears, the mod is working. If not, check the server logs for errors.
  8. Share the mod with players. For players to see the item, they must also have the mod installed on their client. Place the same .pak file in their local mods folder (usually Starbound/mods in the game directory). If you want to avoid forcing players to install mods, you can use the assetSources approach with a workshop mod, but that’s more complex.

Common Mistakes

  • Wrong folder path: Putting mods in the wrong directory (e.g., the game’s mods folder instead of the server’s).
  • Missing dependencies: Some custom items require other mods (like a library mod). Check the mod description for dependencies.
  • Using a mod that changes game mechanics: If the mod adds new damage types or status effects, it may not work with the server’s base game version.
  • Forgetting to restart the server: Mods are loaded at startup, so a restart is mandatory.
  • Incorrect item ID: Trying to spawn an item with the wrong ID. Use the ID from the mod’s .json file (e.g., myweapon not myweapon.sword).

Tips

  • Test mods locally first: Before adding to a live server, test the mod on a single-player world to ensure it doesn’t crash.
  • Back up your server files: Always back up the server folder before making changes, especially if you have a large player base.
  • Use a mod manager for local testing: Tools like Starbound Mod Manager can help you enable/disable mods quickly.
  • Keep mods organized: Name your mod folders clearly and use a consistent naming scheme for .pak files.
  • Check server logs: The log file (usually starbound.log in the server directory) will show any mod loading errors. Look for lines containing “Error” or “Failed to load”.

Troubleshooting

Item doesn’t appear in-game: First, confirm the mod is loaded by checking the server console for a message like “Loaded mod: MyMod”. If not, ensure the .pak file is in the correct folder and the server was restarted. If the mod is loaded but the item doesn’t spawn, check the item ID – you may need to use the full path (e.g., /spawnitem mymod:myweapon).

Server crashes on startup: This usually indicates a mod incompatibility. Remove the most recently added mod and restart. If it still crashes, check the log for the specific error. Common causes: outdated mod for the server version, or a mod that requires a client-side mod that isn’t installed.

Players can’t see the item: This happens when the client doesn’t have the mod. Make sure players install the same mod version. If you’re using a hosting service, you may need to provide the mod to players via a download link.

Item is invisible or has missing textures: This usually means the .png files are missing or incorrectly referenced. Check the mod’s folder structure – the images must be in the exact path specified in the .json file.

Mod works in single-player but not on server: This can happen if the server is running a different version of Starbound than your client. Ensure both are updated to the same version.

Frequently Asked Questions

Q: Do players need to install the mod to join my server?
A: Yes, if the mod adds new items or assets, players must have the mod installed locally to see and use them. Otherwise, they’ll see a placeholder or the item won’t exist.

Q: Can I add items without a mod?
A: No, custom items require modding. You can create your own items by writing JSON files and creating textures, but that’s essentially making a mod.

Q: How do I create a custom item from scratch?
A: Create a folder in the mods directory, then create a subfolder like items/active/weapons/melee/sword. Inside, create a .json file defining the item’s properties (name, damage, etc.) and a .png file for the icon. You can use existing items as templates.

Q: What is the difference between a .pak and a folder mod?
A: A .pak is a compressed archive that loads faster and is easier to distribute. A folder mod is a directory with loose files. Both work, but .pak is preferred for servers.

Q: Can I use Steam Workshop mods on my server?
A: Yes, but you need to download the mod files from the Workshop and place them in the server’s mods folder. The server doesn’t have Steam Workshop integration by default.

Q: Will adding mods affect server performance?
A: Minorly. Each mod adds a small amount of memory and load time. Large mods with many assets can increase RAM usage. Monitor your server’s performance after adding mods.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.