Editing Modding (section)

== Steam Workshop ==

WSR ships with Steam Workshop support for sharing mods. Subscribed Workshop items are downloaded by Steam, copied into a per-user staging directory at startup, and overlaid on top of the install directory at the file-protocol layer. '''The install directory is never modified''' - Steam's "verify integrity of game files" stays a no-op for Workshop content, and mods survive a full reinstall.

=== How it works for players ===

# Open the game's Workshop page in Steam, subscribe to a mod.
# Steam downloads the mod content to its UGC folder.
# Next time you launch Wall Street Raider, the game mirrors that folder into <code>%LOCALAPPDATA%\Wall Street Raider\workshop\installed\&lt;id&gt;\</code> and builds a merged overlay at <code>%LOCALAPPDATA%\Wall Street Raider\workshop\overlay\</code>.
# When the renderer asks for a file (<code>js/locale/de.js</code>, <code>css/variables.css</code>, etc.), Electron's file-protocol interceptor checks the overlay first and falls through to the install dir if the file isn't there.

In-game: '''Main Menu &rarr; Workshop''' opens the subscribed-mods list. Each row shows the mod's current Steam state with color coding:
* '''Installed''' (green) - downloaded, will apply on next game restart
* '''Downloading…''' / '''Queued''' (cyan) - Steam is fetching the content; wait, then restart
* '''Subscribed (not downloaded)''' (yellow) - Steam hasn't started downloading; click the '''Force Download''' button on that row to prompt it
* '''Update available''' (yellow) - newer version exists on Workshop; click Force Download
The list auto-refreshes every 3 seconds while the modal is open, so status changes are visible without closing and reopening.

Other modal buttons:
* '''Browse Workshop in Steam''' - opens the WSR Workshop page in the Steam overlay (or your default browser if the overlay is off)
* '''Publish a Mod…''' - launches the bundled Mod Uploader (see [[#Publishing a mod|§Publishing a mod]])
* '''Unsubscribe''' (per row) - removes the subscription; effective on next restart

{{Note|Mod changes take effect on the '''next''' game launch. Subscribed mods aren't hot-swapped into a running session - JS modules cache after first fetch, so overlay rebuilds mid-session wouldn't reach the running renderer.}}

=== What can be in a Workshop mod ===

A Workshop mod is '''a zip of replacement files mirroring the <code>resources/app/</code> tree'''. Everything listed earlier in this guide is fair game:

* <code>css/variables.css</code>, <code>css/theme.css</code>, <code>css/components/*.css</code> (themes)
* <code>js/locale/&lt;code&gt;.js</code> plus an updated <code>js/locale/localeManager.js</code> (locales)
* <code>js/data/hints/*.js</code> (contextual hints)
* <code>assets/*.png</code> / <code>*.jpg</code> / <code>*.mp4</code> / <code>*.ico</code> (asset reskins, same filenames)
* <code>assets/help/wsrbook.htm</code> (rewritten manual)
* <code>CORPNAME.DAT</code> (renamed companies / tickers)
* '''New''' Preact component files plus a one-line import in <code>js/app.js</code> or a parent component (additive UI mods are the cleanest way to avoid collisions with other mods)

You '''cannot''' mod through Workshop:
* <code>wsr.exe</code> or <code>ui.dll</code> (binaries, blocked from the overlay for safety)
* Engine simulation rules (engine doesn't read mods)
* Save format

=== Conflict resolution ===

If two subscribed mods both ship a <code>css/variables.css</code>, '''last-loaded wins''' and a warning is logged to <code>wsr-stdio.log</code> listing the conflict. There is no in-game enable/disable toggle in v1 - if two mods collide and you don't like the result, unsubscribe from the one whose changes you don't want.

=== Publishing a mod ===

The '''WSR Mod Uploader''' is bundled with the game. Two ways to launch it:

* '''From inside WSR:''' Main Menu &rarr; Workshop &rarr; '''Publish a Mod…'''
* '''Direct from your install dir:''' <code>&lt;install&gt;\mod-uploader\wsr-mod-uploader.exe</code>

The uploader is a thin GUI around <code>ISteamUGC::CreateItem</code> / <code>SubmitItemUpdate</code>. Steam must be running.

==== Workflow ====

# '''Mod folder''' - pick the folder containing your mod's files. The picker defaults to <code>&lt;Documents&gt;\WSR Mods\</code>, which is auto-created on first launch. Anything under there shows up as a quick pick. Your folder should mirror the <code>resources/app/</code> structure (see [[#What can be in a Workshop mod|§What can be in a Workshop mod]]).
# '''Preview image''' - pick a PNG or JPG '''under 1 MB''' (Workshop limit, enforced client-side). Required - Workshop rejects items without a preview.
# '''Title''' - 5 to 128 characters. Steam rejects very short titles for public items.
# '''Description''' - at least 30 characters. Same reason.
# '''Tags''' - optional. Pick from the preset checkboxes, type your own comma-separated, or both. See [[#Standard tags|§Standard tags]].
# '''Visibility''' - Public / Friends only / Private. Start with Private while you iterate.
# '''Changelog''' - shown in the Workshop item's revision history. Useful on updates.
# Click '''Publish'''.

The Publish button stays disabled until folder, preview, title, and description are all valid. The status panel at the bottom streams JSON status lines as Steam processes the upload; success ends with <code>Published! Workshop ID: &lt;number&gt;</code> and an '''Open in browser''' button.

==== .wsrmod-id (updates vs new items) ====

On the first successful publish from a folder, the uploader writes <code>.wsrmod-id</code> into that folder containing the assigned <code>PublishedFileId_t</code>. Subsequent publishes from the same folder detect this file and '''update''' the existing Workshop item rather than creating a duplicate. To fork a mod (publish a copy as a new item), delete or move <code>.wsrmod-id</code> out of the folder before publishing.

==== SteamCMD alternative ====

You can also use SteamCMD's <code>+workshop_build_item</code> with a <code>.vdf</code> if you prefer scripting. Same metadata is required. See [https://partner.steamgames.com/doc/features/workshop/implementation#SteamCmd Valve's docs].

==== Standard tags ====

The Wall Street Raider Workshop accepts '''freeform tags by default''' - you can type any tag in the uploader's "Custom tags" field. The convention below is what the in-game Workshop browser groups by, so following it makes your mod easier to discover:

{| class="wikitable"
! Tag !! What it means
|-
| <code>Theme</code> || CSS theme / re-skin (palette, fonts, layout tweaks)
|-
| <code>Locale</code> || Translation pack (full or partial)
|-
| <code>Hints</code> || New / rewritten contextual hints
|-
| <code>Assets</code> || Replacement images, videos, icons
|-
| <code>Companies</code> || Alternate company-name database (<code>CORPNAME.DAT</code>)
|-
| <code>UI Extension</code> || New Preact components or feature additions
|-
| <code>Other</code> || Anything that doesn't fit the categories above
|}

Tags are optional. Multiple tags are fine when a mod spans categories (e.g. a "1929 era" mod might tag <code>Theme</code> + <code>Companies</code> + <code>Assets</code>).

=== Troubleshooting ===

==== For subscribers (using mods) ====

* '''Subscribed mod isn't visible.''' Re-launch the game - mod changes apply at startup only.
* '''Workshop menu says "not available."''' The game must be launched via Steam. Workshop calls require a logged-in Steam client.
* '''Mod is stuck on "Subscribed (not downloaded)" yellow status.''' Click the '''Force Download''' button on that row. Calls <code>ISteamUGC::DownloadItem(id, high_priority=true)</code> to prompt Steam to fetch the content. Watch the status flip to '''Queued''' then '''Downloading…''' then '''Installed'''. If the status doesn't change within ~10 seconds, fully restart the Steam client (Exit, wait, reopen) - subscriptions can fail to sync until Steam reconnects.
* '''Mod's files aren't loading.''' Check <code>%LOCALAPPDATA%\Wall Street Raider\workshop\manifest.json</code> to see which mods were detected and which file paths the overlay owns. If your mod isn't in the <code>mods</code> list, the loader couldn't see its install folder (rare - usually means the Steam content download is still in progress; wait and re-launch).
* '''Two mods conflict.''' Check the same <code>manifest.json</code> for the <code>conflicts</code> array. Last-wins means whichever mod sorted later in the loader's iteration order replaced the conflicting file. Unsubscribe from one of the two.

==== For mod authors (using the uploader) ====

* '''Uploader's Publish button is greyed out.''' One or more required fields aren't satisfied. Yellow hint text under each field shows what's missing (folder picked, preview image, title at least 5 chars, description at least 30 chars).
* '''Upload returns <code>AccessDenied (15)</code> after content reaches 100%.''' Almost always: the Steamworks Workshop config has unpublished changes. Go to the top-nav '''Publish''' tab and push any pending config changes to Steam. If everything's already published, check that '''Steam Cloud quota''' is non-zero for this app and that '''Enable ISteamUGC for file transfer''' is checked.
* '''Upload returns <code>Busy (10)</code> repeatedly.''' The uploader auto-retries 3 times. If still failing: Workshop config for this app likely isn't fully provisioned (the per-app Workshop service hasn't initialized in Steam's backend yet). Wait 10 minutes after publishing any config changes, then retry.
* '''Upload returns <code>InvalidParam (8)</code>.''' One of the metadata fields is rejected. Check the diagnostic <code>{"kind":"params"}</code> line in the uploader's status panel - it shows everything that was sent. Most common cause: title or description too short.
* '''Friend's Steam chat opens whenever I publish.''' Steam shows you as "In-Game: Wall Street Raider" while the uploader's native helper is running, which fires friend-presence notifications. Set your Steam status to '''Invisible''' while testing, OR have the friend disable "Open chat when friend signs in" in their Steam notification settings. There's no clean code-level fix.
* '''Cleanup: empty / placeholder Workshop items from failed publishes.''' Each <code>CreateItem</code> succeeds even when <code>SubmitItemUpdate</code> later fails, leaving an empty Workshop item that auto-subscribes you. Visit [https://steamcommunity.com/my/myworkshopfiles/?appid=3525620 your Workshop submissions page], click into each empty/no-title item, and delete it (Edit &rarr; Delete). Also unsubscribe from them via Main Menu &rarr; Workshop in-game.

[[Category:Modding]]
[[Category:Wall Street Raider]]