Modding

New Stars supports mods through the Steam Workshop. You can publish your own content packs and turn any mod you've subscribed to on or off from inside the game — no file copying, no restart. This page covers the two in-game panels — the Workshop Uploader (for publishing mods) and the Mod Manager (for enabling and disabling them) — and how mods are kept in sync when you play multiplayer.

What a content pack can contain

A content pack is a folder of files, sorted into named subfolders by type. Include whichever subfolders you need — empty or missing ones are skipped.

Subfolder	Contents	Where it appears in-game
Icons/	.png / .jpg empire icons	Empire icon picker on the empire creation screen
Portraits/	.png / .jpg species portraits	Species portrait picker on the empire creation screen
Presets/Empires/	.sav empire presets	Empire preset list, alongside the built-in presets
Presets/Maps/	.sav map presets	Map preset list, alongside the built-in presets
Events/	.yaml game-event definitions	Natural & colony events that roll and fire during play

A typical pack root looks like:

My Pack/
  Icons/              empire icon images
  Portraits/          species portrait images
  Presets/
    Empires/          empire preset .sav files
    Maps/             map preset .sav files
  Events/             game-event .yaml files (one event per file)

Empire and map presets

To put a preset in a pack, save it in-game as you normally would, then copy its .sav file out of your local presets folder into the pack's Presets/Empires/ or Presets/Maps/ subfolder.

• Presets that arrive from a pack appear in the preset lists marked as Workshop content and are read-only — they can't be edited or deleted, only loaded. (Loading one copies it into your game, just like a built-in preset.)
• Empire presets keep their spawn-state toggle (Not spawnable / Spawnable / Always spawn), so a pack can ship empires that take part in galaxy generation.
• Enabling, disabling, subscribing, or unsubscribing a pack updates the preset lists immediately — no restart needed.
• An empire preset that references a custom icon or portrait you don't have installed falls back to a placeholder for that slot; the preset still loads.

Game events (Events/)

A pack can ship custom game events as .yaml files in an Events/ folder — one event per file. These are the rolling natural and colony events that fire as the galaxy lives: a colony disaster, a stellar phenomenon, a windfall on a settled world. Each file describes, in plain text, when the event can happen, how likely it is, and what it does.

A minimal event looks like:

id: mypack:meteor_shower
type: natural
roll:
  scope: per_system
  once_in_years: 8
can_instigate: "is_colonized and is_disaster_prone"
meta: system.world
text:
  title: "Meteor Shower"
  description: "A meteor shower batters {meta}."
on_instigate:
  - op: damage_buildings

• id is a unique name, namespaced to your pack (e.g. mypack:meteor_shower).
• type is the event category — natural or colony events roll automatically each in-game month.
• roll sets how often it is considered (once_in_years, or a flat probability) and its scope.
• can_instigate is a condition that must hold for the event to fire (e.g. the system is colonized).
• on_instigate is the list of effects applied when it fires (grant resources, change a world's climate, start a storm, damage buildings, and so on).

Enabling or disabling the pack adds or removes its events immediately, like every other content type. The full list of event types, conditions, effects, and more worked examples is on the Event authoring page.

Current scope: custom events roll on the server and apply their world-changing effects, which all players see. Multi-step events with player-choice pop-ups (pick option A or B) are not yet surfaced for custom events, so for now keep custom events to automatic effects. Built-in game, colony and planet events are unchanged.

Uploading a mod

Open the Workshop Uploader from the mods menu. The left sidebar lists every pack you already own, plus a New pack entry, so it's always clear whether you're creating a new mod or editing an existing one.

Placeholder — Workshop Uploader panel. Replace with screenshot of the upload screen.

To publish a new pack:

1. Click New pack in the sidebar. A blank draft opens, marked Draft · not published.
2. Enter a Title and Description.
3. Click Browse next to Content folder and select the folder containing your mod's files.
4. Click Browse next to Preview image and pick a .png or .jpg thumbnail.
5. Choose a Visibility: Private, Friends, or Public.
6. (Optional) Add a change note describing the update.
7. Click Publish New Pack. The progress bar tracks the upload; when it finishes, your draft becomes a published pack with its own Workshop ID.

To update a pack you already own, select it in the sidebar, change whatever you need, and click Publish Update.

Preview image requirements

Steam rejects uploads without a valid preview image, so the uploader checks yours before submitting. The image must:

• be a .png, .jpg, or .jpeg file (not a folder),
• be under 1 MB in size, and
• sit outside the content folder, so it isn't double-counted as mod content.

If any check fails, the status line explains what to fix and nothing is uploaded.

Notes

• A draft has no Workshop ID until its first successful upload. You can remove an unpublished draft with Delete draft. Already-published packs are owned by Steam and can only be removed from the Steam client.
• Only one upload runs at a time.
• If Steam isn't running, the uploader still lets you fill in a draft but can't publish until Steam is available.

Enabling and disabling mods

Open the Mod Manager from the mods menu. It lists every Workshop mod you're subscribed to — each row shows the mod's icon, title, description, and an on/off switch. The header summary reads, for example, 2 OF 5 ENABLED.

Placeholder — Mod Manager panel. Replace with screenshot of the subscribed-mods list.

• To enable or disable a mod, click its switch. The change is saved and applied immediately — there's no need to restart the game. Disabling a mod leaves your subscription intact; it just stops loading.
• The list refreshes every time you open the panel, so newly subscribed mods appear automatically.
• Press Esc or click the × to close.

To add mods to this list, subscribe to them on the Steam Workshop; they'll download in the background and show up the next time you open the Mod Manager. A mod still downloading appears with the note Not installed yet — Steam is still downloading this mod.

If you aren't subscribed to anything yet, the panel shows: You're not subscribed to any mods yet. Browse the Steam Workshop to subscribe.

Playing with mods in multiplayer

So everyone in a game sees the same content, New Stars keeps a lobby's mods in sync with the host. When you join, the game compares the mods the host has enabled against your own and fills in anything you're missing.

• The host's installed and enabled Workshop mods are advertised to the lobby automatically (and re-advertised if the host toggles a mod while the lobby is open). Mods the host has switched off, and local development folders that were never published to the Workshop, are not shared.
• Auto-download lobby mods — a switch in Settings → Gameplay, on by default. While it's on, any of the host's mods you don't already have are subscribed, downloaded, and enabled for you automatically in the background. They load live, with no restart, the moment Steam finishes each download.
• If the setting is off and you're missing one or more of the host's mods, a popup appears listing them, with two choices:
  • Download & Enable — fetch and switch on the missing mods now (just like the automatic flow, but only for this lobby's mods).
  • Continue Anyway — dismiss the popup and join without them. You may then see different content from the rest of the lobby.
• Mods you pick up for a lobby are kept afterwards. Leaving the lobby does not unsubscribe them or switch them off, so rejoining — or using that content in your own games — needs no re-download. You can always turn them off later in the Mod Manager.

A mod the host is using that is private or otherwise not available to your Steam account can't be downloaded; the popup will leave it listed and you'll be missing that content until the host makes it accessible.

Troubleshooting

Symptom	Cause / fix
"Steam isn't running"	Start Steam, then reopen the panel. Workshop features need the Steam client.
A subscribed mod is missing	It may still be downloading. Reopen the Mod Manager once Steam finishes.
Upload won't start	Check that the title, content folder, and a valid preview image are all set — the status line names the missing piece.
Preview rejected	Use a .png/.jpg under 1 MB, stored outside the content folder.
A pack's presets don't appear	Confirm the pack is enabled in the Mod Manager and that its presets sit in Presets/Empires/ or Presets/Maps/ as .sav files.
A pack's events don't fire	Confirm the pack is enabled, that each event is its own .yaml file under Events/, and that it has a unique id and a type of natural or colony. Events only roll during play, so give them time (or check their roll cadence).
The "missing mods" popup keeps appearing when joining games	Turn on Auto-download lobby mods in Settings → Gameplay, or click Download & Enable in the popup. A private mod the host uses that your account can't access can't be downloaded.
Mods didn't download when joining a lobby	Make sure Auto-download lobby mods is on, that Steam is running, and that you can reach the Workshop. Host-side, only published, installed, and enabled mods are shared — local-only folders are not.