Editing Modding (section)

= Wall Street Raider - Modding Guide =

A reference for everything you can mod in WSR with nothing but a text editor. The Electron frontend has '''no build step''' and the install ships with <code>asar: false</code>, so every file under <code>resources/app/</code> is a normal editable file. '''Edit, CTRL+R, see your change.'''

What you '''can't''' mod without recompiling: the PowerBASIC engine (<code>wsr.exe</code>), the C++ bridge (<code>ui.dll</code>), and the binary <code>.DAT</code>/<code>.PRM</code> files.

{{Note|Back up before you edit. Steam's "verify integrity of game files" reverts changes - that's also your safety net.}}

== TL;DR - what's moddable ==

{| class="wikitable"
! I want to… !! Do this
|-
| Re-theme the game || Edit <code>css/variables.css</code>, then <code>css/theme.css</code> / <code>css/components/</code>
|-
| Change UI text / layout / behavior || Edit the relevant file in <code>js/components/</code>
|-
| Add a new panel or feature || New file in <code>js/components/</code>, import it from a parent or <code>app.js</code>
|-
| Replace a background video or image || Drop a same-named file into <code>assets/</code>
|-
| Rewrite the manual || Edit <code>assets/help/wsrbook.htm</code>
|-
| Add a language || New <code>js/locale/&lt;code&gt;.js</code> + register in <code>localeManager.js</code>
|-
| Change / add contextual hints || Edit files in <code>js/data/hints/</code>
|-
| Rename companies / tickers / nations || Edit <code>CORPNAME.DAT</code> (plain text). Effective on '''next New Game'''.
|-
| Drive the game from JS || Call an <code>api.js</code> function ([[#Calling the API from a frontend mod|§api.js]])
|-
| Drive the game from a third-party app || Hit the REST API directly ([[#REST API reference|§REST API]])
|-
| Read game state || <code>useGameStore(s =&gt; s.gameState.&lt;field&gt;)</code> or <code>GET /gamestate</code> ([[#gameState reference|§gameState]])
|-
| Persist your mod's data in saves || <code>setCustomData({ myKey: … })</code> ([[#CustomData - your persistent storage|§CustomData]])
|-
| Share a mod with other players || Steam Workshop ([[#Steam Workshop|§Workshop]])
|-
| Change a core simulation rule || '''Not moddable.''' Requires engine source + recompile.
|}

== Architecture in one breath ==

<pre>
PowerBASIC engine  →  C++ bridge DLL (REST + WebSocket)  →  Electron UI
   wsr.exe              ui.dll                                everything you see
</pre>

At launch, <code>ui.dll</code> picks ephemeral REST + WS ports and writes them to <code>%LOCALAPPDATA%\Wall Street Raider\runtime.json</code>:

<pre>
{ "pid": 12345, "rest_port": 54321, "ws_port": 54322 }
</pre>

Electron reads that file and hands the ports to the renderer; <code>js/api.js</code> builds <code>http://127.0.0.1:&lt;rest&gt;</code> and <code>ws://127.0.0.1:&lt;ws&gt;</code>. WS pushes a full snapshot on connect, then JSON-patch diffs; if WS drops, the UI polls <code>GET /gamestate</code>.

'''Third-party apps:''' read <code>runtime.json</code> the same way. Ports change every launch.

== File layout ==

In source (<code>electron/</code>) and in an installed copy (<code>&lt;install&gt;/resources/app/</code>) the layout is identical - the install is a verbatim copy of the source tree (see <code>extraFiles</code> in <code>electron/package.json</code>):

<pre>
resources/app/
├── index.html              # entry point
├── main.js                 # Electron main process
├── js/                     # ← all frontend code (editable)
│   ├── app.js              #   Preact root, WS wiring, hotkeys
│   ├── api.js              #   REST/WS client, gameStore, ID constants, endpoint wrappers
│   ├── components/         #   100+ Preact panels/modals/tables/tabs
│   ├── hooks/              #   useCookie, useInterval, usePanelSelection, …
│   ├── services/           #   hintMatcher.js, …
│   ├── utils/              #   misc
│   ├── icons.js            #   inline SVG
│   ├── debug-log.js        #   frontend logging
│   ├── lib/                #   vendored: preact, zustand, tailwind, fast-json-patch
│   ├── locale/             #   ← translations
│   └── data/hints/         #   ← contextual hints
├── css/                    # ← all styling (editable)
├── assets/                 # ← images / videos / icons / help (editable)
├── CORPNAME.DAT            # ← plain-text company database (editable)
├── wsr.exe                 # engine (binary)
├── ui.dll                  # bridge (binary)
└── *.DAT / *.PRM           # other game data (binary/encoded - leave alone)
</pre>

== Frontend code (<code>js/</code>) ==

Components use '''Preact + htm''' (JSX-like template literals, no compile step) and '''Zustand''' for state. Minimal example:

<pre>
import { html, Component } from '../lib/preact.standalone.module.js';
import { useGameStore } from '../api.js';

export function MyPanel() {
    const cash = useGameStore(s =&gt; s.gameState.cash);
    return html`&lt;div class="p-4"&gt;Cash: ${cash}&lt;/div&gt;`;
}
</pre>

You can:
* Edit any existing component (layout, text, colors, behavior).
* Add new components and import them into <code>app.js</code> or any parent.
* Add new hotkeys (grep <code>hotkey</code>; handling lives in <code>app.js</code> + <code>HotkeyButtonBar.js</code>).
* Add new buttons that call any API endpoint ([[#Calling the API from a frontend mod|§api.js]]).
* Add new derived displays from <code>gameState</code> ([[#gameState reference|§gameState]]).

== Styling (<code>css/</code>) ==

<pre>
css/
├── style.css               # the file index.html links - imports the rest
├── base.css                # resets / base element styles
├── variables.css           # ← CSS custom properties (theme palette lives here)
├── theme.css               # theme layer
├── layout.css              # app layout
├── chart-styles.js         # chart styling injected as JS
├── components/             # buttons, dropdown, forms, modals, panels, tables, tabs
├── features/               # assets, calculator, help, market, menu, notes, ticker, tutorial
└── pages/                  # game, main-menu, quotes
</pre>

Tailwind utilities are also available via <code>js/lib/tailwind.module.js</code>, so most components use Tailwind inline + the modular CSS for anything custom.

'''To re-theme:''' start with <code>variables.css</code> - override the custom properties and the whole app follows.

== Assets (<code>assets/</code>) ==

{| class="wikitable"
! What !! Files
|-
| Background videos || the many <code>*.mp4</code> (Wall Street footage, industry b-roll, …)
|-
| Event images || <code>blackswan.png</code>, <code>ponzi.jpg</code>, <code>soupline.jpg</code>, <code>zimbabwe.jpg</code>, <code>helicopter.jpg</code>, <code>yacht.mp4</code>
|-
| Branding / logos || <code>wallstreetraider_logo.png</code>, <code>hackjackgames_logo.png</code>, <code>roninsoft_logo.png</code>
|-
| Social widgets || <code>discord-widget.png</code>, <code>reddit-widget.png</code>
|-
| Loading spinner || <code>loading.gif</code>
|-
| App icon || <code>wsr.ico</code>
|}

Replace any of these with a same-named file of the same type. '''Keep filenames identical''' - components reference them by name.

== Help content (<code>assets/help/</code>) ==

<code>wsrbook.htm</code> is the in-game manual - one ~1 MB plain HTML file. Edit it directly. The <code>*.jpg</code> files in the same folder are diagrams it embeds. <code>electron/UI_HELP_CATALOG.txt</code> is a developer catalog of help sections.

== Translations (<code>js/locale/</code>) ==

Pure data - '''no engine changes needed to add a language.'''

How it works (<code>localeManager.js</code>):
* <code>LANGUAGE_OPTIONS</code> maps locale code → <code>{ name, dictionary, warning? }</code>.
* Each <code>dictionary</code> is a flat <code>{ "English source": "translation", … }</code>.
* The <code>translator</code> does runtime lookup/replacement on UI strings.
* Existing locales: <code>zh-CN.js</code>, <code>es-419.js</code>, <code>ja-JP.js</code>, <code>pt-BR.js</code>, <code>ru-RU.js</code>.

To add a language:

<pre>
// js/locale/fr-FR.js
export const frFR = {
    "New Game": "Nouvelle partie",
    "Buy Stock": "Acheter des actions",
    // … one entry per source string you want translated
};

// js/locale/localeManager.js
import { frFR } from './fr-FR.js';
// …
'fr-FR': { name: 'Français', dictionary: frFR },
</pre>

The chosen locale persists in <code>CFIG.WSR</code>, surfaces as <code>gameState.locale</code>, and switches via <code>POST /set_locale</code>.

{{Note|Missing strings fall through to English, so a partial translation is fine. The <code>*-backup-*</code> files are timestamped editing backups (git-ignored) - ignore them.}}

== Contextual hints (<code>js/data/hints/</code>) ==

Hint files are grouped by view and aggregated by <code>index.js</code>:

<pre>
hints/
├── index.js          # aggregates all sets
├── global.js         # fallback hints
├── company.js        # while viewing a company
├── industry.js
├── market.js
├── modals.js
├── player.js
├── portfolio.js
└── swap-info-text.js
</pre>

Each entry:

<pre>
{
    id: 'company-overview-controlled-etf',
    match: { view: 'company', tab: 'overview', controls: true, entityKind: 'mutual-fund' },
    title: 'Advising an ETF',
    content: `&lt;p&gt;HTML body shown to the player…&lt;/p&gt;`,
}
</pre>

<code>js/services/hintMatcher.js</code> picks the most specific match for the current screen. Rewrite text, add new hints, retarget <code>match</code> conditions - no engine changes.

== Company names (<code>CORPNAME.DAT</code>) ==

Plain pipe-delimited text:

<pre>
0011|00|JPB  |  J.P. MULLINS WALL ST. BANK |
0012|00|UBC  |  URBAN BANCORP |
0015|26|KYOB |  KYOTO BANK |
</pre>

Columns: <code>company ID | nation code | ticker | name</code>. Read by the engine's <code>GetCorpNames</code> at '''new-game''' time, so edits take effect on the '''next''' new game (not on already-saved games). Rename companies, change tickers, change a company's home nation.

'''Keep the format exact:''' 4-digit zero-padded ID, 2-digit nation code, fixed-width symbol field, and the surrounding <code>|</code> + spacing. <code>CORPNAME.ORI</code> is the pristine original - keep as your backup.

== Other game data (don't bother) ==

{| class="wikitable"
! File(s) !! Content !! Why limited
|-
| <code>QUOTEWSR.DAT</code> || quote of the day || encoded; <code>quotehs.prm</code> is a near-plaintext source the engine doesn't read
|-
| <code>MSCNEWS.DAT</code> || news / scenario headlines || encoded; same story with <code>MSCNEWS.PRM</code>
|-
| <code>scenwin1-4.prm</code> || scenario window text || engine-internal format
|-
| <code>GAME01-50.DAT</code> || save slots / scenario data || proprietary binary
|-
| <code>WSR101.DAT</code>, <code>REGINFO.DAT</code>, … || engine data || proprietary binary
|}

Treat as read-only. <code>CORPNAME.DAT</code> is the one truly editable game-data file.

== Calling the API from a frontend mod ==

<code>js/api.js</code> is the '''wrapper layer''' for the REST API: each endpoint has a named async function with semantic parameters, plus the live <code>gameStore</code>, plus exported '''ID constants''' (entity IDs, industry indices, special asset IDs, <code>UI_*</code> report IDs). '''Frontend mods should call <code>api.js</code> functions, not raw HTTP.'''

<pre>
import * as api from '../api.js';

await api.buyStock(companyId);                    // /buy_stock
await api.setDividend(actingAsId);                // /set_dividend
await api.merger(targetId, actingAsId);           // /merger
await api.cheatAddCash();                         // /cheat_add_cash
const state = await api.getGameState();           // GET /gamestate
</pre>

For endpoints that don't have a named wrapper yet, four request shapes are also exported:

{| class="wikitable"
! Helper !! Body shape !! Use
|-
| <code>postNoArg(path)</code> || <code>{}</code> || actions with no parameter
|-
| <code>postIdArg(path, id)</code> || <code>{ id }</code> || actions on a specific entity / slot
|-
| <code>postIdArgWithActingAs(path, id, actingAsId)</code> || <code>{ id, intParam2 }</code> || most corporate / trade actions
|-
| <code>postOptionsTradeWithActingAs(path, id, actingAsId, underlyingId)</code> || <code>{ id, intParam2, underlyingId }</code> || options trades
|-
| <code>postStringArg(path, str)</code> || <code>{ str }</code> || actions taking a string (e.g. save-as filename)
|-
| <code>getJSON(path)</code> || - || GET endpoints
|}

For wire-level details (the underlying routes, the JSON body the bridge actually receives, what each generic field means per endpoint), see [[#REST API reference|§REST API reference]].

== REST API reference ==

For third-party apps and direct integrations. Frontend mods should prefer <code>api.js</code> ([[#Calling the API from a frontend mod|§api.js]]).

=== Conventions ===

* '''Base URL:''' <code>http://127.0.0.1:&lt;rest_port&gt;</code>. Read <code>rest_port</code> from <code>%LOCALAPPDATA%\Wall Street Raider\runtime.json</code>; ports change every launch.
* '''Content-Type:''' <code>application/json</code> on all POSTs.
* '''Generic body schema:''' the bridge accepts a single envelope <code>{ id?, intParam2?, underlyingId?, str?, answer?, value?, filename? }</code>. Each endpoint uses 0-3 of these fields with '''endpoint-specific meanings''' - the per-endpoint tables below spell out which fields are read and what they mean in context.
* '''Omitted fields default to 0 / empty.''' Most action endpoints can be called as <code>{}</code> if they don't strictly need params (the engine often falls back to "use the currently active entity" or "show the picker modal").
* '''Most actions open a modal''' rather than executing immediately. After POSTing, the engine pushes a modal state via WS / <code>gameState.modalType</code>; respond with <code>POST /modal_result</code>.

==== The <code>actingAsId</code> pattern ====

Most corporate / trade endpoints accept an '''<code>actingAsId</code>''' (sent as the JSON field <code>intParam2</code>): the entity that '''executes''' the action.

* <code>0</code> (or omitted) = act as the player.
* Any other ID = act as that controlled company. The engine momentarily switches context, runs the action ''as that company'', then restores.

When the per-endpoint tables below show <code>intParam2</code>, it means actingAsId unless noted otherwise.

==== Response shape ====

GET endpoints return endpoint-specific JSON (documented in the GET table). POST endpoints return <code>{ status: "ok" }</code> on success and a <code>{ error: "…" }</code> with HTTP 4xx/5xx on failure. Side effects show up via the next WS broadcast.

=== GET endpoints ===

{| class="wikitable"
! Method !! Endpoint !! Returns
|-
| GET || <code>/status</code> || health check
|-
| GET || <code>/gamestate</code> || full game-state JSON ([[#gameState reference|§gameState]])
|-
| GET || <code>/quote</code> || <code>{ quote: string }</code> - quote of the day
|-
| POST || <code>/asset_chart</code> || body <code>{ id }</code>; returns 60 months of price history for an asset (<code>{ prices, highs, lows, xAxisTitle, yAxisTitle, baseMonth, baseYear }</code>)
|-
| GET || <code>/database_data</code> || searchable database of all companies (industry, financials, ratings, …)
|-
| GET || <code>/ownership_tree</code> || ownership hierarchy of the active entity (who owns it, at what %)
|-
| GET || <code>/subsidiaries_tree</code> || what the active entity owns (its subsidiaries, at what %)
|}

=== Session / clock ===

{| class="wikitable"
! Endpoint !! Body !! Description
|-
| POST <code>/newgame</code> || <code>{}</code> || Start a new game.
|-
| POST <code>/loadgame</code> || <code>{}</code> || Open the load-game flow.
|-
| POST <code>/load_specific_save</code> || <code>{ filename }</code> || Load a specific save. <code>filename</code> = save basename; must not contain <code>..</code>, <code>/</code>, <code>\</code>, <code>:</code>.
|-
| POST <code>/savegame</code> || <code>{}</code> || Save to the default slot.
|-
| POST <code>/savegameas</code> || <code>{ filename }</code> || Save under a name. Empty <code>filename</code> shows the Save-As dialog.
|-
| POST <code>/exit_game</code> || <code>{}</code> || Exit to main menu.
|-
| POST <code>/check_scoreboard</code> || <code>{}</code> || Open the scoreboard view.
|-
| POST <code>/start_ticker</code> || <code>{}</code> || Start the market ticker animations.
|-
| POST <code>/run_ticker</code> || <code>{}</code> || Advance the ticker by one queue item.
|-
| POST <code>/stop_ticker</code> || <code>{}</code> || Stop the ticker.
|-
| POST <code>/set_ticker_speed</code> || <code>{ id }</code> || Set ticker speed. <code>id</code> = speed enum.
|-
| POST <code>/ticker_advance</code> || <code>{}</code> || Pop the front of the ticker queue, append a new item.
|-
| POST <code>/clear_event_string</code> || <code>{}</code> || Clear the event message log.
|-
| POST <code>/splash_screen_played</code> || <code>{}</code> || Mark splash as shown so it's skipped next time.
|}

=== Trading - stocks & bonds ===

{| class="wikitable"
! Endpoint !! Body !! Description
|-
| POST <code>/buy_stock</code> || <code>{ id, intParam2? }</code> || Buy stock. <code>id</code> = company to buy. <code>intParam2</code> = actingAsId.
|-
| POST <code>/sell_stock</code> || <code>{ id, intParam2? }</code> || Sell stock. <code>id</code> = company to sell. <code>intParam2</code> = actingAsId.
|-
| POST <code>/short_stock</code> || <code>{ id, intParam2? }</code> || Open short. <code>id</code> = company to short. <code>intParam2</code> = actingAsId.
|-
| POST <code>/cover_short_stock</code> || <code>{ id, intParam2? }</code> || Cover an existing short. <code>id</code> = company. <code>intParam2</code> = actingAsId.
|-
| POST <code>/buy_corporate_bond</code> || <code>{ id, intParam2? }</code> || Buy a corporate bond. <code>id</code> = issuing company. <code>intParam2</code> = actingAsId.
|-
| POST <code>/sell_corporate_bond</code> || <code>{ id, intParam2? }</code> || Sell a corporate bond. <code>id</code> = issuing company. <code>intParam2</code> = actingAsId.
|-
| POST <code>/buy_long_govt_bonds</code> || <code>{ intParam2 }</code> || Buy long-term govt bonds. <code>intParam2</code> = actingAsId. <code>id</code> ignored.
|-
| POST <code>/sell_long_govt_bonds</code> || <code>{ intParam2 }</code> || Sell long-term govt bonds. <code>intParam2</code> = actingAsId.
|-
| POST <code>/buy_short_govt_bonds</code> || <code>{ intParam2 }</code> || Buy short-term govt bonds. <code>intParam2</code> = actingAsId.
|-
| POST <code>/sell_short_govt_bonds</code> || <code>{ intParam2 }</code> || Sell short-term govt bonds. <code>intParam2</code> = actingAsId.
|}

=== Trading - commodities & crypto ===

{| class="wikitable"
! Endpoint !! Body !! Description
|-
| POST <code>/buy_commodity_futures</code> || <code>{ id, intParam2? }</code> || Buy commodity futures. <code>id</code> = commodity ID (e.g. <code>OIL_ID</code>, <code>GOLD_ID</code>). <code>intParam2</code> = actingAsId.
|-
| POST <code>/sell_commodity_futures</code> || <code>{ id, intParam2? }</code> || Sell commodity futures. <code>id</code> = commodity ID. <code>intParam2</code> = actingAsId.
|-
| POST <code>/close_long_commodity_futures_by_slot</code> || <code>{ id, intParam2? }</code> || Close a specific long position. <code>id</code> = '''portfolio slot index''' (not a commodity ID). <code>intParam2</code> = actingAsId.
|-
| POST <code>/short_commodity_futures</code> || <code>{ id, intParam2? }</code> || Short commodity futures. <code>id</code> = commodity ID. <code>intParam2</code> = actingAsId.
|-
| POST <code>/cover_short_commodity_futures</code> || <code>{ id, intParam2? }</code> || Cover commodity short. <code>id</code> = commodity ID. <code>intParam2</code> = actingAsId.
|-
| POST <code>/cover_short_commodity_futures_by_slot</code> || <code>{ id, intParam2? }</code> || Cover a specific short position. <code>id</code> = '''portfolio slot index'''. <code>intParam2</code> = actingAsId.
|-
| POST <code>/buy_physical_commodity</code> || <code>{ id, intParam2? }</code> || Buy physical commodity. <code>id</code> = commodity ID. <code>intParam2</code> = actingAsId.
|-
| POST <code>/sell_physical_commodity</code> || <code>{ id, intParam2? }</code> || Sell physical commodity. <code>id</code> = commodity ID. <code>intParam2</code> = actingAsId.
|-
| POST <code>/buy_physical_crypto</code> || <code>{ id, intParam2? }</code> || Buy physical crypto. <code>id</code> = crypto ID (e.g. <code>BITCOIN_ID</code>). <code>intParam2</code> = actingAsId.
|-
| POST <code>/sell_physical_crypto</code> || <code>{ id }</code> || Sell physical crypto. <code>id</code> = crypto ID. (No actingAs param on this one.)
|-
| POST <code>/buy_crypto_futures</code> || <code>{ id, intParam2? }</code> || Buy crypto futures. <code>id</code> = crypto ID. <code>intParam2</code> = actingAsId.
|-
| POST <code>/sell_crypto_futures</code> || <code>{ id, intParam2? }</code> || Sell crypto futures. <code>id</code> = crypto ID. <code>intParam2</code> = actingAsId.
|}

=== Trading - options ===

{| class="wikitable"
! Endpoint !! Body !! Description
|-
| POST <code>/buy_calls</code> || <code>{ id, intParam2?, underlyingId? }</code> || Buy calls. <code>id</code> = strike-price ID (or 0 to show the strike picker). <code>intParam2</code> = actingAsId. <code>underlyingId</code> = company being optioned (when <code>id&gt;0</code> and <code>underlyingId&gt;0</code>, modal is skipped — used by CLI flows like "CALL ABC").
|-
| POST <code>/sell_calls</code> || <code>{ id, intParam2?, underlyingId? }</code> || Sell calls. Same param semantics as <code>/buy_calls</code>.
|-
| POST <code>/buy_puts</code> || <code>{ id, intParam2?, underlyingId? }</code> || Buy puts. Same param semantics as <code>/buy_calls</code>.
|-
| POST <code>/sell_puts</code> || <code>{ id, intParam2?, underlyingId? }</code> || Sell puts. Same param semantics as <code>/buy_calls</code>.
|-
| POST <code>/advanced_options_trading</code> || <code>{ intParam2 }</code> || Open the advanced options panel (spreads, collars). <code>intParam2</code> = actingAsId.
|-
| POST <code>/exercise_call_options_early</code> || <code>{ id, intParam2? }</code> || Exercise a call early. <code>id</code> = call contract ID. <code>intParam2</code> = actingAsId.
|-
| POST <code>/exercise_put_options_early</code> || <code>{ id, intParam2? }</code> || Exercise a put early. <code>id</code> = put contract ID. <code>intParam2</code> = actingAsId.
|}

=== Corporate management ===

All of these operate on the acting-as entity. <code>id</code> is unused unless noted; pass <code>0</code> or omit.

{| class="wikitable"
! Endpoint !! Body !! Description
|-
| POST <code>/prepay_taxes</code> || <code>{ intParam2 }</code> || Prepay taxes. <code>intParam2</code> = actingAsId.
|-
| POST <code>/elect_ceo</code> || <code>{ intParam2 }</code> || Open CEO-election picker for the entity. <code>intParam2</code> = actingAsId.
|-
| POST <code>/resign_as_ceo</code> || <code>{ intParam2 }</code> || Acting-as entity resigns as CEO. <code>intParam2</code> = actingAsId.
|-
| POST <code>/change_managers</code> || <code>{ intParam2 }</code> || Hire / fire managers. <code>intParam2</code> = actingAsId.
|-
| POST <code>/set_dividend</code> || <code>{ intParam2 }</code> || Set the company's dividend. <code>intParam2</code> = actingAsId (dividend issuer).
|-
| POST <code>/set_productivity</code> || <code>{ intParam2 }</code> || Set productivity. <code>intParam2</code> = actingAsId.
|-
| POST <code>/set_growth_rate</code> || <code>{ intParam2 }</code> || Set growth rate. <code>intParam2</code> = actingAsId.
|-
| POST <code>/restructure</code> || <code>{ intParam2 }</code> || Open restructuring modal. <code>intParam2</code> = actingAsId.
|-
| POST <code>/buy_corporate_assets</code> || <code>{ intParam2 }</code> || Buy plant / equipment. <code>intParam2</code> = actingAsId.
|-
| POST <code>/sell_corporate_assets</code> || <code>{ intParam2 }</code> || Sell plant / equipment. <code>intParam2</code> = actingAsId.
|-
| POST <code>/offer_corporate_assets_for_sale</code> || <code>{ intParam2 }</code> || List assets for other entities to buy. <code>intParam2</code> = actingAsId.
|-
| POST <code>/view_for_sale_items</code> || <code>{ intParam2 }</code> || Browse assets currently for sale. <code>intParam2</code> = actingAsId.
|-
| POST <code>/sell_subsidiary_stock</code> || <code>{ id, intParam2? }</code> || Sell stock the entity holds in a subsidiary. <code>id</code> = subsidiary company ID. <code>intParam2</code> = actingAsId (seller).
|-
| POST <code>/rebrand</code> || <code>{ intParam2 }</code> || Rename the company. <code>intParam2</code> = actingAsId.
|-
| POST <code>/toggle_company_autopilot</code> || <code>{ id }</code> || Toggle one company's autopilot. <code>id</code> = company.
|-
| POST <code>/toggle_global_autopilot</code> || <code>{ intParam2 }</code> || Toggle autopilot across all of the entity's holdings. <code>intParam2</code> = actingAsId.
|-
| POST <code>/become_etf_advisor</code> || <code>{ intParam2 }</code> || Become ETF advisor. <code>intParam2</code> = actingAsId.
|-
| POST <code>/set_advisory_fee</code> || <code>{ intParam2 }</code> || Set the ETF advisory fee. <code>intParam2</code> = actingAsId.
|-
| POST <code>/decrease_earnings</code> || <code>{ intParam2 }</code> || Accounting adjustment to lower reported earnings. <code>intParam2</code> = actingAsId.
|-
| POST <code>/increase_earnings</code> || <code>{ intParam2 }</code> || Accounting adjustment to raise reported earnings. <code>intParam2</code> = actingAsId.
|}

=== M&A / corporate finance ===

{| class="wikitable"
! Endpoint !! Body !! Description
|-
| POST <code>/merger</code> || <code>{ id, intParam2? }</code> || Start a merger. <code>id</code> = target company. <code>intParam2</code> = actingAsId (acquirer).
|-
| POST <code>/greenmail</code> || <code>{ id, intParam2? }</code> || Greenmail (coercive buyback). <code>id</code> = target. <code>intParam2</code> = actingAsId.
|-
| POST <code>/lbo</code> || <code>{ id, intParam2? }</code> || Leveraged buyout. <code>id</code> = target. <code>intParam2</code> = actingAsId.
|-
| POST <code>/startup</code> || <code>{ intParam2 }</code> || Found a new startup. <code>intParam2</code> = actingAsId (founder).
|-
| POST <code>/capital_contribution</code> || <code>{ intParam2 }</code> || Inject cash into a subsidiary. <code>intParam2</code> = actingAsId.
|-
| POST <code>/public_stock_offering</code> || <code>{ intParam2 }</code> || IPO. <code>intParam2</code> = actingAsId (company going public).
|-
| POST <code>/private_stock_offering</code> || <code>{ intParam2 }</code> || Private placement. <code>intParam2</code> = actingAsId.
|-
| POST <code>/issue_new_corp_bonds</code> || <code>{ intParam2 }</code> || Issue new corporate bonds. <code>intParam2</code> = actingAsId (issuer).
|-
| POST <code>/redeem_corp_bonds</code> || <code>{ intParam2 }</code> || Retire outstanding bonds. <code>intParam2</code> = actingAsId.
|-
| POST <code>/extraordinary_dividend</code> || <code>{ intParam2 }</code> || One-time special dividend. <code>intParam2</code> = actingAsId.
|-
| POST <code>/tax_free_liquidation</code> || <code>{ intParam2 }</code> || Liquidate with tax deferral. <code>intParam2</code> = actingAsId.
|-
| POST <code>/taxable_liquidation</code> || <code>{ intParam2 }</code> || Liquidate; pay tax on gains. <code>intParam2</code> = actingAsId.
|-
| POST <code>/spin_off</code> || <code>{ id, intParam2? }</code> || Spin off a subsidiary. <code>id</code> = subsidiary to spin off. <code>intParam2</code> = actingAsId (parent).
|-
| POST <code>/split_stock</code> || <code>{ intParam2 }</code> || Forward stock split. <code>intParam2</code> = actingAsId.
|-
| POST <code>/reverse_split_stock</code> || <code>{ intParam2 }</code> || Reverse stock split. <code>intParam2</code> = actingAsId.
|}

=== Banking / loans / swaps ===

{| class="wikitable"
! Endpoint !! Body !! Description
|-
| POST <code>/borrow_money</code> || <code>{ intParam2 }</code> || Take out a loan. <code>intParam2</code> = actingAsId (borrower).
|-
| POST <code>/repay_loan</code> || <code>{ intParam2 }</code> || Pay down / repay. <code>intParam2</code> = actingAsId.
|-
| POST <code>/advance_funds</code> || <code>{ intParam2 }</code> || Lender advances cash against securities. <code>intParam2</code> = actingAsId (lender).
|-
| POST <code>/call_in_advance</code> || <code>{ id }</code> || Terminate an advance. <code>id</code> = advance ID.
|-
| POST <code>/interest_rate_swaps</code> || <code>{ id, intParam2? }</code> || Open the swaps modal. <code>id</code> = asset ID. <code>intParam2</code> = actingAsId.
|-
| POST <code>/view_swap_details</code> || <code>{ id, intParam2? }</code> || View one swap's details. <code>id</code> = swap ID. <code>intParam2</code> = actingAsId.
|-
| POST <code>/terminate_swap</code> || <code>{ id, intParam2? }</code> || Terminate a swap early. <code>id</code> = swap ID. <code>intParam2</code> = actingAsId.
|-
| POST <code>/set_bank_allocation</code> || <code>{ intParam2 }</code> || Distribute cash across banks. <code>intParam2</code> = actingAsId.
|-
| POST <code>/trade_tbills</code> || <code>{ intParam2 }</code> || Trade T-bills. <code>intParam2</code> = actingAsId.
|-
| POST <code>/list_bank_loans</code> || <code>{ intParam2 }</code> || List the entity's outstanding bank loans (when acting as a bank). <code>intParam2</code> = actingAsId.
|-
| POST <code>/change_bank</code> || <code>{ intParam2 }</code> || Change primary bank. <code>intParam2</code> = actingAsId.
|-
| POST <code>/call_in_loan</code> || <code>{ id }</code> || Demand immediate repayment. <code>id</code> = loan ID.
|-
| POST <code>/buy_bank_loans</code> || <code>{}</code> || Open the bank-loans investment picker.
|-
| POST <code>/buy_business_loans</code> || <code>{ intParam2 }</code> || Buy business-loan portfolio. <code>intParam2</code> = actingAsId (investor).
|-
| POST <code>/sell_business_loan</code> || <code>{ id }</code> || Sell one business-loan holding. <code>id</code> = loan ID.
|-
| POST <code>/buy_consumer_loans</code> || <code>{ intParam2 }</code> || Buy consumer-loan portfolio. <code>intParam2</code> = actingAsId.
|-
| POST <code>/sell_consumer_loans</code> || <code>{ intParam2 }</code> || Sell consumer-loan holdings. <code>intParam2</code> = actingAsId.
|-
| POST <code>/buy_prime_mortgages</code> || <code>{ intParam2 }</code> || Buy prime mortgages. <code>intParam2</code> = actingAsId.
|-
| POST <code>/sell_prime_mortgages</code> || <code>{ intParam2 }</code> || Sell prime mortgages. <code>intParam2</code> = actingAsId.
|-
| POST <code>/buy_subprime_mortgages</code> || <code>{ intParam2 }</code> || Buy subprime mortgages. <code>intParam2</code> = actingAsId.
|-
| POST <code>/sell_subprime_mortgages</code> || <code>{ intParam2 }</code> || Sell subprime mortgages. <code>intParam2</code> = actingAsId.
|-
| POST <code>/list_etfs</code> || <code>{}</code> || Show available ETFs.
|-
| POST <code>/freeze_all_loans</code> || <code>{ intParam2 }</code> || Freeze all loan repayments across the lender's portfolio. <code>intParam2</code> = actingAsId.
|-
| POST <code>/freeze_loan</code> || <code>{ id }</code> || Freeze one specific loan. <code>id</code> = loan ID.
|}

=== Legal / dirty tricks ===

{| class="wikitable"
! Endpoint !! Body !! Description
|-
| POST <code>/change_law_firm</code> || <code>{ intParam2 }</code> || Hire a law firm. <code>intParam2</code> = actingAsId.
|-
| POST <code>/credit_info</code> || <code>{ intParam2 }</code> || Show credit info (rating, history). <code>intParam2</code> = actingAsId.
|-
| POST <code>/antitrust_lawsuit</code> || <code>{ id, intParam2? }</code> || Sue for antitrust. <code>id</code> = target company. <code>intParam2</code> = actingAsId (plaintiff).
|-
| POST <code>/harrassing_lawsuit</code> || <code>{ id, intParam2? }</code> || File a frivolous lawsuit. <code>id</code> = target. <code>intParam2</code> = actingAsId.
|-
| POST <code>/spread_rumors</code> || <code>{ id, intParam2? }</code> || Spread rumors to damage stock / reputation. <code>id</code> = target company. <code>intParam2</code> = actingAsId.
|}

=== Reports / views / navigation ===

{| class="wikitable"
! Endpoint !! Body !! Description
|-
| POST <code>/set_active_ui_report</code> || <code>{ id }</code> || Switch active report panel. <code>id</code> = a <code>UI_*</code> enum (see <code>api.js</code> constants).
|-
| POST <code>/set_view_asset</code> || <code>{ id }</code> || Navigate to a company / player. <code>id</code> = entity ID. Updates nav history.
|-
| POST <code>/set_view_industry</code> || <code>{ id }</code> || Navigate to an industry overview. <code>id</code> = industry index, or <code>-2</code> = trigger DB Search.
|-
| POST <code>/database_search</code> || <code>{}</code> || Open the database search interface.
|-
| POST <code>/clear_chart</code> || <code>{}</code> || Clear the active price chart.
|-
| POST <code>/growth_throttle</code> || <code>{}</code> || Open growth-throttle settings.
|-
| POST <code>/clear_stream_list</code> || <code>{}</code> || Clear the streaming-quotes watchlist.
|-
| POST <code>/fill_stream_list</code> || <code>{}</code> || Populate the streaming-quotes watchlist with defaults.
|-
| POST <code>/toggle_streaming_quote</code> || <code>{ id }</code> || Toggle live updates for one asset. <code>id</code> = company / asset.
|-
| POST <code>/nav_back</code> || <code>{}</code> || Nav history: back.
|-
| POST <code>/nav_forward</code> || <code>{}</code> || Nav history: forward.
|-
| POST <code>/nav_clear</code> || <code>{}</code> || Clear nav history.
|-
| POST <code>/nav_goto</code> || <code>{ id }</code> || Jump to a nav-history index. <code>id</code> = position in history stack.
|-
| POST <code>/nav_set_history</code> || JSON array || Restore nav history from saved state. Body = array of <code>{ id, type }</code> where <code>type</code> is <code>"asset"</code> or <code>"industry"</code>, most-recent-first.
|-
| POST <code>/set_who_owns_filter</code> || <code>{ value }</code> || Set the "who owns what" filter. <code>value</code> = filter enum.
|-
| POST <code>/view_current_interest_rates</code> || <code>{}</code> || Show current interest rates.
|-
| POST <code>/whos_ahead</code> || <code>{}</code> || Show the leaderboard.
|-
| POST <code>/db_research_tool</code> || <code>{}</code> || Open the research database tool.
|-
| POST <code>/economic_stats</code> || <code>{}</code> || Show macro stats.
|-
| POST <code>/most_cash_report</code> || <code>{}</code> || Most-cash leaderboard.
|-
| POST <code>/largest_market_cap</code> || <code>{}</code> || Market-cap leaderboard.
|-
| POST <code>/largest_tax_losses</code> || <code>{}</code> || Largest carried-forward tax losses.
|-
| POST <code>/industry_summary</code> || <code>{}</code> || Industry summary stats.
|-
| POST <code>/industry_projections</code> || <code>{}</code> || Industry growth / decline projections.
|-
| POST <code>/view_corp_assets_for_sale</code> || <code>{}</code> || All corporate assets currently for sale.
|}

=== Settings / toggles ===

These all open a settings menu / cycle the toggle. No params except where noted.

{| class="wikitable"
! Endpoint !! Body !! Description
|-
| POST <code>/supp_earn_select</code> || <code>{}</code> || Suppress earnings-warnings menu.
|-
| POST <code>/currency_select</code> || <code>{}</code> || Currency selection.
|-
| POST <code>/supp_warn_select</code> || <code>{}</code> || Suppress-warnings menu.
|-
| POST <code>/suppress_select</code> || <code>{}</code> || Suppress messages / alerts menu.
|-
| POST <code>/autosave_select</code> || <code>{}</code> || Autosave settings.
|-
| POST <code>/exercise_select</code> || <code>{}</code> || Auto-exercise options settings.
|-
| POST <code>/sweep_select</code> || <code>{}</code> || Cash-sweep settings.
|-
| POST <code>/makedelivery_select</code> || <code>{}</code> || Make-delivery settings (commodity/crypto).
|-
| POST <code>/takedelivery_select</code> || <code>{}</code> || Take-delivery settings.
|-
| POST <code>/tooltips_select</code> || <code>{}</code> || Tooltip enable / disable.
|-
| POST <code>/shareholdergraph_select</code> || <code>{}</code> || Shareholder-graph display settings.
|-
| POST <code>/disablehotkeys_select</code> || <code>{}</code> || Hotkey enable / disable.
|-
| POST <code>/autoadd_select</code> || <code>{}</code> || Auto-add-to-watchlist settings.
|-
| POST <code>/set_chart_type</code> || <code>{ id }</code> || Set chart style. <code>id</code> = chart type enum.
|-
| POST <code>/set_locale</code> || <code>{ str }</code> || Set UI locale. <code>str</code> = locale code (e.g. <code>"en-US"</code>, <code>"ja-JP"</code>).
|}

=== Cheat menu ===

{| class="wikitable"
! Endpoint !! Body !! Description
|-
| POST <code>/cheat_disable</code> || <code>{}</code> || Lock cheats off.
|-
| POST <code>/cheat_disable_lawsuits</code> || <code>{}</code> || Disable lawsuits entirely.
|-
| POST <code>/cheat_merger_info</code> || <code>{}</code> || Reveal hidden merger info.
|-
| POST <code>/cheat_earnings_info</code> || <code>{}</code> || Reveal earnings forecasts and hidden financials.
|-
| POST <code>/cheat_add_cash</code> || <code>{}</code> || Add a fixed amount of cash. (No "set cash to N" - this is fixed.)
|}

=== Modals ===

{| class="wikitable"
! Endpoint !! Body !! Description
|-
| POST <code>/close_modal</code> || <code>{}</code> || Close the current modal.
|-
| POST <code>/modal_result</code> || <code>{ answer }</code> or <code>{ str }</code> || Submit the player's modal response. Use <code>answer</code> for numeric / choice modals; <code>str</code> for text-entry modals.
|}

=== Tutorial ===

{| class="wikitable"
! Endpoint !! Body !! Description
|-
| POST <code>/set_tutorial_step</code> || <code>{ id }</code> || Jump tutorial to a step. <code>id</code> = step number.
|-
| POST <code>/set_tutorial_enabled</code> || <code>{ id }</code> || Enable / disable tutorial. <code>id</code> = <code>1</code> on, <code>0</code> off.
|}

=== Price alerts ===

{| class="wikitable"
! Endpoint !! Body !! Description
|-
| POST <code>/show_price_alerts</code> || <code>{}</code> || Open the alerts management dialog.
|-
| POST <code>/create_price_alert</code> || <code>{ str }</code> || Create an alert. <code>str</code> = pipe-delimited <code>"entityId|direction|targetPrice"</code>; direction is <code>"up"</code> or <code>"down"</code>.
|-
| POST <code>/delete_price_alert</code> || <code>{ id }</code> || Delete one alert. <code>id</code> = alert slot index.
|}

=== CustomData ===

{| class="wikitable"
! Endpoint !! Body !! Description
|-
| POST <code>/set_custom_data</code> || JSON object || Shallow-merge mod data into <code>customData</code>. See [[#CustomData - your persistent storage|§CustomData]].
|}

== gameState reference ==

<code>GET /gamestate</code> returns one JSON object - ~90 top-level fields - that is the complete read model. In a frontend mod, subscribe to only the fields you need so you only re-render on those:

<pre>
const cash = useGameStore(s =&gt; s.gameState.cash);
const year = useGameStore(s =&gt; s.gameState.currentYear);
</pre>

{| class="wikitable"
! Group !! Fields
|-
| '''Player''' || <code>cash</code>, <code>otherAssets</code>, <code>totalAssets</code>, <code>totalDebt</code>, <code>netWorth</code>, <code>playerId</code>, <code>playerName</code>, <code>chairedCompanyId</code>
|-
| '''Clock / session''' || <code>currentYear</code>, <code>currentQuarter</code>, <code>currentMonth</code>, <code>currentDay</code>, <code>currentTime</code>, <code>nextEarningsDate</code>, <code>gameLoaded</code>, <code>gameOver</code>, <code>readyToRestart</code>, <code>isTickerRunning</code>, <code>tickSpeed</code>, <code>splashScreenPlayed</code>
|-
| '''Active selection''' || <code>activeEntityNum</code>, <code>activeEntityName</code>, <code>activeEntitySymbol</code>, <code>activeIndustryNum</code>, <code>activeIndustryId</code>, <code>actingAsId</code>, <code>actingAsName</code>, <code>actingAsSymbol</code>, <code>actingAsIndustryId</code>, <code>actingAs</code>
|-
| '''Modal state''' || <code>modalType</code>, <code>modalText</code>, <code>modalTitle</code>, <code>modalDefault</code>, <code>modalFilter</code>
|-
| '''Collections''' || <code>allCompanies</code>, <code>allPlayers</code>, <code>allSecurities</code>, <code>allIndustries</code>, <code>controlledCompanies</code>, <code>tickerQueue</code>, <code>streamingQuotesList</code>, <code>newsHeadlines</code>, <code>trendingNews</code>, <code>navHistory</code>, <code>navPointerIndex</code>
|-
| '''Active entity detail''' || <code>activeEntityData</code>, <code>activeEntityFinancials</code> (deep: cash/assets/debt/equity/EPS/cash-flow/…), <code>activeEntityPlayerFinancials</code>, <code>financialProfile</code>, <code>cashflowProjection</code>, <code>portfolio</code>, <code>portHoldings</code>, <code>swapsPortfolio</code>, <code>optionsList</code>, <code>commodityList</code>, <code>shareholdersList</code>, <code>researchReport</code>, <code>advisorySummary</code>, <code>earningsReport</code>, <code>advances</code>, <code>loansReport</code>, <code>myCorporationsReport</code>
|-
| '''Market reports''' || <code>whoOwns*Report</code> (futures, physical commodities, options, swaps, stocks, investment contracts), <code>industrySummaryReport</code>, <code>industryProjectionReport</code>, <code>industryGrowthRatesReport</code>, <code>mostMarketShareReport</code>, <code>mostTaxLossReport</code>, <code>mostCashReport</code>, <code>mostMarketCapReport</code>, <code>economicDataReport</code>, <code>interestRatesReport</code>, <code>whosAheadReport</code>
|-
| '''Settings''' || <code>suppEarnSetting</code>, <code>suppWarnSetting</code>, <code>supPopupSetting</code>, <code>autosaveSetting</code>, <code>exerciseItSetting</code>, <code>sweepSetting</code>, <code>makeDeliverySetting</code>, <code>takeDeliverySetting</code>, <code>tooltipsSetting</code>, <code>shareholderGraphSetting</code>, <code>unethicalSetting</code>, <code>disableHotkeysSetting</code>, <code>chartType</code>, <code>locale</code>
|-
| '''Tutorial / misc''' || <code>tutorialEnabled</code>, <code>tutorialStep</code>, <code>alerts</code>, <code>frozenAllLoans</code>, <code>dlrSign</code>, <code>euro</code>, '''<code>customData</code>''' ([[#CustomData - your persistent storage|§CustomData]])
|}

The exact shape can change between versions - the authoritative move is to <code>GET /gamestate</code> from a running game. <code>Ctrl+Shift+I</code> opens DevTools; <code>gameStore.getState().gameState</code> in the console dumps the live object.

== CustomData - your persistent storage ==

<code>customData</code> is a free-form JSON object that '''rides along inside the save file'''. The engine never reads it for simulation - it stores it verbatim, writes it into the <code>.WSR</code>/<code>.DAT</code> save, restores it on load, and exposes it on every <code>gameState</code> as <code>gameState.customData</code>.

This is the supported way for a mod to persist its own state per-save.

=== Read ===

<pre>
const customData = useGameStore(s =&gt; s.gameState?.customData ?? {});
const myStuff = customData.myModKey;
</pre>

=== Write ===

<pre>
import { setCustomData } from '../api.js';
await setCustomData({ myModKey: { highScore: 42, notes: 'hello' } });
</pre>

=== Semantics ===

* '''Shallow merge.''' <code>POST /set_custom_data</code> merges into the existing <code>customData</code> at the '''top level''' - incoming top-level keys overwrite, others are preserved. '''Namespace your data under one top-level key''' (e.g. <code>myModKey</code>) and write that whole sub-object each time.
* '''Round-trips.''' New value comes back on the next <code>gameState</code> broadcast.
* '''Inert.''' Cannot change cash, prices, or any engine value - only action endpoints can ([[#REST API reference|§REST API]]).
* '''Per-save.''' Saved/loaded with the game; a fresh New Game starts empty.

=== Reserved top-level keys ===

The base UI already stores a few things in <code>customData</code>. '''Don't reuse these keys''':

{| class="wikitable"
! Key !! Used by !! Contents
|-
| <code>notes</code> || Notes modal || free-text notes
|-
| <code>navHistory</code> || Navigation system || saved nav history
|-
| (DB search criteria) || Database Search view || saved filters / sort
|-
| (holdings prefs) || Portfolio Holdings table || saved filters / sort / hide-subsidiaries
|}

Pick a unique key for your mod (e.g. <code>customData["mymod:state"]</code>).

== Limits - what you '''can't''' do ==

* '''No raw memory / pointer writes.''' Only curated endpoints. The only free-form write is <code>customData</code>, and it's inert.
* '''No intercepting the update loop.''' WS delivers a snapshot. Read and react; you cannot mutate values mid-update or inject into serialization.
* '''No new engine behavior without recompiling.''' New mechanic / event type / endpoint = edit PowerBASIC source (<code>src/main/wsr/*.inc</code>, ~178K lines), rebuild <code>wsr.exe</code> (PB 9.80) and usually <code>ui.dll</code> (VS C++). That's engine development, not modding.
* '''No editing binary game data.''' Saves and most <code>.DAT</code>/<code>.PRM</code> are proprietary binary or encoded. <code>CORPNAME.DAT</code> is the one safe exception.

== Workflow ==

=== Edit / test ===

# Edit a file under <code>js/</code>, <code>css/</code>, <code>assets/</code>, or <code>CORPNAME.DAT</code>.
# Restart the game (no hot reload).
# <code>Ctrl+Shift+I</code> for DevTools - console errors, the <code>gameStore</code>, network tab against the REST API.

=== Packaging for others ===

A mod is '''a set of replacement files'''. Simplest distribution: a zip mirroring the <code>resources/app/</code> structure:

<pre>
my-dark-theme/
├── css/variables.css
└── css/theme.css
</pre>

Install instructions: "drop these into <code>resources/app/</code>, overwriting."

Good practice:
* Keep mods '''additive''' where possible - new component files wired in with one import line, not rewrites of core files. Two additive mods are less likely to collide.
* Document which base files you replace.
* Tell users that Steam's "verify integrity of game files" reverts changes (their uninstall path) and to back up originals.

== 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]]