Recommended Free Tools
To add a custom item to a Starbound dedicated server, create a uniquely named mod under the server’s mods directory, add a modinfo manifest, place the item’s JSON and any PNG or Lua files in paths that mirror Starbound’s asset tree, and configure the server to search that mods directory. For an existing vanilla item, a JSON patch is usually safer than replacing the complete definition. Stop both server and client while editing, validate the files, then test the mod with a fresh character and universe before using it in an established multiplayer save.
Prefer not to run the server on your own PC? Godlike.Host offers hosted Starbound servers with free DDoS protection and up to three free backups a day.
How Starbound loads a custom item
Starbound does not read an item from an arbitrary folder. It resolves content through an asset tree. The moddable base tree is in /Starbound/assets, and a mod can add matching files through the mods tree. A modinfo file anywhere in that mods directory tree marks the containing mod content for loading.
As an Amazon Associate I earn from qualifying purchases.
An item normally consists of a JSON definition. That definition may refer to an inventory icon, animation, projectile, sound, or Lua script, so those referenced assets must also exist at the paths Starbound expects. The practical rule is to copy the directory structure and field names from a comparable item that already works in your Starbound build, then change only the values you need.
Standalone item or modification?
There are two different jobs often described as “adding an item.” A standalone item introduces a new itemName and its own assets. A modification changes an existing item, recipe, table, or other asset. Use a standalone definition when the item should have its own identity. Use a .patch file when you are extending or changing an existing definition; patches target specific paths and avoid copying an entire vanilla file that may change in a later game update.
#1 Best Overall
- [Ultra-Lightweight Ear Buds Designed for Small Ears] Each earbud weighs only 3.7g and features a compact, ergonomic in-ear design made especially for small ears. Secure, low-profile, and comfortable for workouts, all-day wear or overnight sleeping.The ultra-slim profile sits flush in your ear with no hard edges poking or rubbing, so you can even sleep on your side without discomfort.
- [Immersive Stereo Sound with TOZO OrigX Technology] TOZO OrigX tuning delivers clear vocals, balanced mids, and natural stereo sound for music, podcasts, and videos.
- [Long Battery Life for Daily Use] Get up to 7 hours of playtime on a single charge, with up to 32 hours total using the charging case—ideal for workdays, commuting, and extended listening sessions.
- [Bluetooth 5.3 & Stable Connection] Bluetooth 5.3 provides fast pairing, stable wireless performance, and reduced dropouts as you move around home or office.
- [Deep Bass with Clear Vocals] High-performance drivers produce punchy bass while keeping vocals clean and detailed for everyday listening.
Prepare a safe test copy
Back up the save and stop every process
Back up the server’s storage directory and, if you will test locally, your player and universe files. Stop the dedicated server and exit the game completely before changing files. Check that no starbound.exe process remains. A stale process can keep old assets in memory and make a corrected file appear broken.
Inspect a working item first
Unpack or inspect the base assets and find an item with the same broad behavior as yours. A material, a gun, an active item, armor, an instrument, and a liquid do not share the same complete set of fields. Copying a gun definition into a material folder, or retaining behavior fields that belong to another item type, is a common cause of loading errors.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Use a JSON-aware editor. The Starbound modding portal specifically recommends Visual Studio Code because it highlights malformed punctuation and structural errors while you edit. Validate the file before starting the server.
Create the mod directory and manifest
Use a unique folder under the server’s mods directory
Create a folder whose name is unlikely to collide with another mod, for example MyCustomItems. Keep the item JSON, images, and scripts below that folder while preserving the corresponding asset-tree paths. A typical layout is:
Rank #2
- 【IP68 Waterproof Multifunctinal Smart Watch】Torjalph fitness activity tracker smart watch is IP68 waterproof technology ,you can wear it when swimming,handwashing,it's rain-proof which means that you perform multiple exercise modes outside without worrying about sweat or rain corroding your fitness smart watch,and this watch equipped with a 230 mAh large capacity battery magnetic charging ,and this sports activity tracker watch can be used 5-7 days If fully charged.
- 【Larger 1.83'' Full Screen Watch & Multi-dial Selection】1.83 inch full HD color touch screen smart watch for men / women provides excellent 240*284 resolution image quality ,This Bluetooth smart watch offers a better touch experience and remarkable immersion and ,more than 200 watch faces for you to choose from App"Da Fit ", you can change the dial style according to your mood to wear keeping the world on your wrist
- 【Accurate Activity Tracker Smart Watch 】sports watch activity tracker uses sweat and dust resistant breathable silicone strap, our Fitness Tracker Smart Watch for Android iOS Phones supports 12 sports modes,walking,running,bicycle,swimming,badminton,basketball,football,rope skipping. This bluetooth calls smart watch for men women is lightweight and stylish, bringing more convenient and relaxing sports experience while also providing more protection.
- 【Your 24 Hour Personal Daily Health Monitor】Fitness watch for women men full touch screen IP67 waterproof bluetooth smartwatch for Android iOS Phones with heart rate blood pressure monitor multifunction Andriod smart watch with steps counter sleep monitor sports fitness watch, monitoring blood oxygen saturation allows you to understand your physical condition in real time to track fitness progress ,to know your health status in time.
- 【More Functions Bluetooth Call Smart Watch】This fitness activity smart watch full screen for iPhone and Android phones includes a bunch of new features including:The bluetooth smart watch can hang up the phone, receive and display WhatsAPP /Text /Facebook /Twitter /Messenger reminder.Support sedentary reminder, alarm clock, stopwatch, timer,weather information,music control, remote camera control compatible with Android 5.0 and above or iOS 9.0 and above smartphones.
Starbound/
mods/
MyCustomItems/
modinfo
items/
generic/
mycustomitem.item
mycustomitem.png
scripts/
mycustomitem.luaThe exact extension and subdirectory depend on the asset you are defining. Follow the extension and location used by the comparable vanilla file you copied. The important parts are that the files are inside the mod folder and that their internal paths match the paths used by the JSON definition.
Add a modinfo file
The manifest is required even when the item definition itself is valid. A minimal manifest commonly used for a local Starbound mod is:
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errors{
"name": "MyCustomItems",
"version": "1.0",
"path": "."
}Save it as a file named modinfo in the mod’s root, without an extra .json suffix. If an existing mod in your installation uses additional manifest fields, retain the field format accepted by your build and keep the name unique. The loader’s key requirement is that a valid modinfo is present in the mods directory tree.
Define a new item in JSON
Choose the matching category directory
Item definitions are grouped by type. Common locations include /active, /armors, /generic, /guns, /instruments, /liquids, and /materials (often beneath an items directory in the physical asset tree). Use the path used by the comparable vanilla definition in your installation rather than guessing from the item’s appearance.
Rank #3
- [Low Noise High Fidelity] New bee guitar cord with 22AWG oxygen-free-copper center conductors provides enhanced signal transfer, the PVC insulation material and the high-density stranded copper double shield provide noise rejection for quiet operation
- [Ideal for Choice] New bee 1/4 straight and right angle metal connectors, ensures a secure connection in any instrument, pedal, or amp jack. L shape great fro on stage guitar stands
- [Wide Compatible] Suitable for mixer, power amplifier, microphone, effector, decoder, equalizer, electoronic organ, electric guitar, electric bass and other electronic equipments. Widely used in the installation of smart home, karaoke speaker, professional stage audio, etc
- [Easy Disassemble] Making incidental repairs quick and easy! Very nice, flexible cable
- [Dont Hesite to Order] 24 hours customer services and professional technology team are standing by
| Item kind | What to copy | Extra files commonly needed |
|---|---|---|
| Generic or material | A simple stackable item with an inventory icon and pickup data | Usually a PNG icon; recipe or drop files may be separate |
| Active item | An item with use behavior, cooldowns, and an activation mode | Animation, projectile, sound, or Lua files as referenced |
| Gun or instrument | A definition with the same firing or performance behavior | Projectiles, animation frames, sounds, and possibly scripts |
| Armor | A matching armor piece with status and wearable fields | Body, head, or back sprites and image directives |
| Liquid | A liquid definition with the correct liquid-specific fields | Liquid icon or related world effects where referenced |
Give the item a unique identity
Start with the working definition and change its identity and presentation. At minimum, check the item’s itemName, display text, rarity, category, inventory icon or image directive, and any behavior fields appropriate to the item type. The itemName must be unique across every mod loaded by the server; reusing a vanilla or another mod’s name can make one definition override the other or leave the result ambiguous.
This abbreviated example shows the kind of fields a simple item may contain. It is an illustration of structure, not a universal schema: replace it with the fields from the comparable item in your Starbound build.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minute{
"itemName": "mycustomitem",
"price": 100,
"rarity": "common",
"category": "materials",
"inventoryIcon": "mycustomitem.png",
"shortdescription": "My Custom Item",
"description": "A test item for this server."
}If the definition points to mycustomitem.png, place that PNG at the relative location expected by the image directive. If it points to animation frames, sounds, or Lua, copy those files into the matching mod paths as well. A valid JSON file cannot compensate for a missing image or script.
Keep JSON strictly valid
Starbound’s configuration format is JSON. Every opening brace and bracket needs a matching close; property names and string values need quotation marks; entries need commas except after the final entry. Do not add comments, trailing commas, or fields copied from an unrelated item type. Unsupported fields can fail during loading even when the punctuation is correct.
Rank #4
- Digital Family Calendar: BSIMB digital calendar wall touch screen puts an end to your chaotic life. Designed for busy families, the digital calendar keeps you organised and in step with your family. Assign different colours and tasks to each family member to make family scheduling easier and more intuitive.
- Easy Setup and Auto-Sync: Plug in, connect to WLAN and auto-syn your electric calendar in minutes. Digital wall calendar compatible with Google calendar, iCloud calendar, Outlook calendar, Cozi calendar and Yahoo calendar. Add events directly on the device or through the ecalendar app. Electronic calendar stays current whether you're at work or traveling—no manual updates needed.
- All-In-One Home Assistant: Smart calendar builds habits and encourage independence with personalised chores. Display daily meal plan to reduce the daily ‘What's for dinner?’ stress. To-do lists keep track of everything you want. Turning chores into valuable achievements with stars and rewards, making life easier and more enjoyable.
- Manage Anytime Anywhere: BSIMB electronic calendar for family stay connected with the powerful ecalendar app. Access and manage your digital wall calendar anytime, anywhere with free features like stars & rewards, photo screensaver, chore charts, meals plans, to-do lists etc. Electronic planner paid features like Magic Import tailor advanced tools for users with special needs.
- Stay in Touch with Loved Ones: Share photos or videos from your phone to electronic wall calendar with app, instantly update your life moment, and keep in touch with your family, especially those who are far away; you can also surprise your smart calendar digital wall by sending him a wish card; it's also great for keeping tech-illiterate elders in touch with the youngsters.
Patch existing content instead of replacing it
For an existing item, recipe, or table, create a .patch file at the path of the asset you want to modify. Patch files are JSON arrays. Every patch object requires an op and a path; supported operations include add, remove, replace, and test.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
[
{
"op": "replace",
"path": "/shortdescription",
"value": "Updated name"
},
{
"op": "add",
"path": "/price",
"value": 250
}
]The path can address a top-level field, a nested field, or a position in a list. Use replace only when the target already exists; use add for a new property or list entry. A test operation can make a patch stop safely when the original value is not what you expected. Check the target path against the current vanilla file, because a path that differs by one level will simply fail to produce the intended result.
Patching is safer than copying a whole vanilla file: it reduces the chance of erasing unrelated fields and makes conflicts with future game updates easier to identify. After creating a patch, verify it with a fresh character and fresh universe before adding it to an established save.
Make the dedicated server load the mod
Confirm the active storage and asset paths
The server must use the storage directory you think it is using and must include the intended mods directory in its asset search paths. If the server is launched with a custom storageDirectory, place the mod under the corresponding installation’s mods location, not under a different client profile.
Check sbinit.config carefully
A Chucklefish forum tutorial published on December 16, 2016 shows an sbinit.config assetDirectories array containing the relative asset and mods paths, represented there as ..assets and ..mods. The same tutorial demonstrates adding a Steam Workshop content directory.
"assetDirectories" : [
"..\assets\",
"..\mods\"
]Treat the Workshop portion of that tutorial as version-sensitive community guidance, not a universal current configuration. Starbound installations and launch methods can use different relative roots, and a path that worked with the 2016 tutorial may not match your current server. Confirm the effective paths in the installation you are running. If the server log never mentions the mod and the folder is correct, the asset search path is the first configuration to investigate.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Test in a controlled order
- Stop everything. Shut down the dedicated server, exit the client, and verify that no Starbound process remains.
- Validate the files. Use the editor’s JSON diagnostics. Check every referenced PNG, Lua script, animation, and relative path.
- Start with only this mod enabled. Temporarily remove other newly added mods from the test configuration so a conflict does not obscure the result.
- Join with a test character. Use the ordinary acquisition route or the server’s established admin-spawn workflow. Confirm that the item appears with the intended name, icon, rarity, and behavior.
- Read
starbound.logimmediately after a failure. The first error is generally more useful than later cascading messages. - Repeat on clean data. Test a fresh character and fresh universe before introducing the item into a long-running multiplayer save.
This sequence separates syntax errors, path errors, server configuration errors, and save-specific problems. Once the item works alone, add other mods back one at a time.
Client and multiplayer compatibility
The documented loading model establishes that item definitions and their referenced assets come from asset trees, but it does not define one rule that covers every item type and every Starbound build. Make the same mod version available wherever the item definition or referenced assets are required, and test with a clean client against the target server. Do not assume that a server-only copy is sufficient for an item whose icon, animation, script, or other client-side asset must be rendered or executed.
Keep the mod folder and manifest versioned together. If you change an item’s fields or assets, distribute the updated folder as one unit rather than mixing an old client copy with a new server copy. Ask players to close the game fully before replacing files so their next launch does not reuse stale loaded content.
Troubleshoot the common failures
| Symptom | Likely cause | What to check |
|---|---|---|
| “Item not found” or no item appears | The definition is outside the loaded tree, has the wrong name, or the server is searching a different mods directory | Confirm the exact file path, unique itemName, modinfo location, active storageDirectory, and assetDirectories. |
| Server or client crashes while loading | Malformed JSON, an unsupported field, or a missing referenced asset | Inspect starbound.log; check braces, brackets, quotation marks, commas, field names, and every PNG, Lua, and animation path. |
| Item exists but its icon or animation is invisible | The image directive is wrong or the PNG is not at the relative path expected by the definition | Compare the directive and file location with a working vanilla item; check capitalization and extension. |
| A patch loads but changes nothing | The target path or operation does not match the current asset, or another patch wins later | Verify the exact nested path, choose add versus replace correctly, remove competing patches during testing, and use fresh character and universe data. |
| Workshop content is ignored | The server’s current configuration does not include the Workshop path used by an older tutorial | Inspect the current sbinit.config and effective asset paths rather than copying the December 16, 2016 example unchanged. |
| One player sees a missing asset while others do not | Client and server mod versions differ, or a required client asset was not distributed | Install the same mod version on the affected client, restart the game completely, and test against a clean character. |
Choose the right implementation approach
| Decision | Prefer this when | Main risk |
|---|---|---|
| Standalone item | You need a new identity, icon, recipe, or behavior | Every JSON and referenced asset path must be complete and unique. |
| JSON patch | You are changing an existing item, recipe, or table | A wrong target path or competing patch can make the change appear ineffective. |
Local mods directory |
You control the server and want the simplest reproducible deployment | Each required client must receive the same compatible files. |
| Workshop distribution | Your deployment process already supports the current Workshop configuration | The 2016 community configuration is version-sensitive and may not match your build. |
| JSON-only item | The item uses existing behavior and assets or only needs a simple icon | A missing icon or inherited field can still break presentation. |
| Item with PNG or Lua assets | The item needs custom visuals or behavior | Relative paths, scripts, and client distribution add more failure points. |
| Fresh test universe | You are validating installation and compatibility | It does not prove that an existing save already containing conflicting content is safe. |
| Established multiplayer universe | The isolated test has passed and you are deploying the finished version | Conflicts or stale player files can make rollback harder, so keep backups. |
Final deployment checklist
- The mod folder has a unique name and contains a valid
modinfofile. - The item definition is in the category path used by a comparable vanilla asset.
- The
itemNameis unique, and all display, rarity, category, and behavior fields match the item type. - Every PNG, Lua script, animation, sound, and image directive resolves within the asset tree.
- Any existing content is changed with a correctly targeted JSON patch instead of an unnecessary full-file replacement.
- The server’s active
storageDirectoryandassetDirectoriesinclude the intended mods directory. - Workshop paths, if used, have been verified against the current installation rather than copied blindly from the 2016 tutorial.
- JSON has been validated, both processes have been fully restarted, and
starbound.loghas been checked. - The mod works alone on a fresh character and fresh universe before deployment to the live multiplayer save.
Bottom line
A reliable Starbound custom item is a small, properly packaged asset-tree mod—not just a JSON file dropped into a random folder. Mirror a working item’s path and schema, mark the mod with modinfo, include every referenced asset, configure the dedicated server’s search paths, and isolate-test the result before distributing it. Use a JSON patch for changes to existing content, and treat Workshop loading instructions from December 16, 2016 as historical guidance that must be checked against your current server build.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
