Editing Modding

= Wall Street Raider - Modding Guide =

This document describes '''everything you can mod today''' in Wall Street Raider, and exactly how to do it. It covers the practical, supported surfaces: the Electron frontend (code, styling, assets, help, translations, hints), the plain-text company-name database, the REST + WebSocket API, and the '''CustomData API''' - the one supported path for writing your own persistent data into a save file.

It does '''not''' cover modifying the PowerBASIC game engine itself (the simulation logic), because that requires recompiling <code>wsr.exe</code> from source with a PowerBASIC 9.80 compiler. Everything below is doable with nothing more than a text editor.

== How the game is built (why modding is easy) ==

WSR is three layers:

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

The crucial fact for modders: '''the Electron frontend has no build step.''' The UI is plain ES modules, plain CSS, and plain asset files loaded directly from disk at runtime. There is no webpack, no transpile, no bundling. The app is packaged with <code>asar: false</code>, which means after installation every file is still a normal editable file on disk - nothing is archived or compressed.

That means: '''edit a file, restart the game, see your change.'''

== Where the files live ==

=== During development (running from source) ===

<pre>
electron/
├── index.html            # app entry point
├── main.js               # Electron main process
├── js/                   # all frontend code
├── css/                  # all styling
├── assets/               # images, videos, icons, help
└── ...
</pre>

=== In an installed / Steam copy ===

After packing, everything lands under the install directory in:

<pre>
&lt;install&gt;/resources/app/
├── index.html
├── main.js
├── js/                   # ← editable
├── css/                  # ← editable
├── assets/               # ← editable
├── wsr.exe               # game engine (binary, not moddable without source)
├── ui.dll                # bridge (binary, not moddable without source)
├── CORPNAME.DAT          # ← editable plain-text company database
├── *.DAT / *.PRM         # other game data (mostly binary/encoded)
└── ...
</pre>

<code>resources/app/js</code>, <code>resources/app/css</code>, and <code>resources/app/assets</code> are copied verbatim from the <code>electron/</code> source tree at pack time (see the <code>extraFiles</code> block in <code>electron/package.json</code>). Editing them in an installed copy works exactly the same as editing them in source.

{{Note|Back up any file before you edit it. A Steam "verify integrity of game files" will revert your changes - that is also your safety net.}}

== What you can mod ==

=== Frontend code - <code>resources/app/js/</code> ===

The entire UI is here, as ES modules. Highlights:

{| class="wikitable"
! Path !! What it is
|-
| <code>js/app.js</code> || Preact root component, WebSocket wiring, gameState polling, hotkey handling
|-
| <code>js/api.js</code> || REST/WebSocket client, the Zustand <code>gameStore</code>, all constants, the command map
|-
| <code>js/components/</code> || 100+ Preact components - every panel, modal, table, tab
|-
| <code>js/hooks/</code> || Reusable Preact hooks (<code>useCookie</code>, <code>useInterval</code>, <code>usePanelSelection</code>, …)
|-
| <code>js/services/</code> || Logic helpers (e.g. <code>hintMatcher.js</code>)
|-
| <code>js/utils/</code> || Misc utilities
|-
| <code>js/icons.js</code> || Inline SVG icon definitions
|-
| <code>js/debug-log.js</code> || Frontend logging
|}

Components use '''Preact + htm''' (JSX-like template literals, no compile step) and '''Zustand''' for state. A minimal component looks like:

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

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

You can freely:
* Change layout, text, colors, behavior of any existing component.
* Add brand-new components and wire them into <code>app.js</code> or any parent.
* Add new hotkeys (search <code>hotkey</code> across <code>js/</code> - the handling lives in <code>app.js</code> and <code>HotkeyButtonBar.js</code>).
* Add new derived/computed displays from <code>gameState</code> (see [[#The gameState - everything you can read|§6]]).
* Add new buttons that call any API endpoint (see [[#The API - everything you can make the game do|§5]]).

Libraries are vendored in <code>js/lib/</code> (<code>preact.standalone.module.js</code>, <code>zustand.module.js</code>, <code>tailwind.module.js</code>, <code>fast-json-patch.module.js</code>) - no npm install needed to develop against them.

=== Styling - <code>resources/app/css/</code> ===

CSS is modular and loaded at runtime. The structure:

<pre>
css/
├── style.css             # the single file index.html links - imports the rest
├── base.css              # resets / base element styles
├── variables.css         # CSS custom properties (THE place for theme colors)
├── 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 utility classes are also available (loaded via <code>js/lib/tailwind.module.js</code>), so most components use Tailwind utilities inline plus the modular CSS for anything custom.

'''To re-theme the game''', start with <code>css/variables.css</code> - it defines the color palette as CSS custom properties. Override those and the whole app follows. For finer control, edit the per-component and per-feature files.

=== Assets - <code>resources/app/assets/</code> ===

All images, videos, icons, and the loading animation:

{| class="wikitable"
! Asset type !! Files
|-
| Background videos || The many <code>*.mp4</code> files (Wall Street footage, industry b-roll, etc.)
|-
| 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 to reskin the game. (Keep filenames identical - components reference them by name.)

=== Help content - <code>resources/app/assets/help/</code> ===

The in-game manual is '''<code>wsrbook.htm</code>''' - a single ~1 MB HTML file. It is plain HTML; edit it directly to rewrite, correct, or extend the manual. The <code>*.jpg</code> files in the same folder are diagrams embedded by the manual (<code>advanopt.jpg</code>, <code>alerts.jpg</code>, <code>automate.jpg</code>, <code>buyloans.jpg</code>, <code>capcont.jpg</code>, <code>treasury.jpg</code>, <code>rlogotxt.jpg</code>).

<code>electron/UI_HELP_CATALOG.txt</code> is a developer reference catalog of help sections - useful to read when navigating the manual.

=== Translations / locales - <code>resources/app/js/locale/</code> ===

WSR ships an English base plus full translation dictionaries. You can add a new language with '''no code changes to the engine''' - it is pure data.

How it works (<code>js/locale/localeManager.js</code>):

* <code>LANGUAGE_OPTIONS</code> maps a locale code → <code>{ name, dictionary, warning? }</code>.
* Each <code>dictionary</code> is a flat object: <code>{ "English source string": "translated string", … }</code>.
* A <code>translator</code> does runtime lookup/replacement on UI strings.
* Existing locale files: <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 or improve a language:

# Create <code>js/locale/&lt;your-locale&gt;.js</code> exporting a dictionary object, e.g.

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

# In <code>js/locale/localeManager.js</code>, import it and add an entry to <code>LANGUAGE_OPTIONS</code>:

<pre>
import { frFR } from './fr-FR.js';
// …
'fr-FR': { name: 'Français', dictionary: frFR },
</pre>
# The chosen locale is persisted by the engine (in <code>CFIG.WSR</code>) and exposed as <code>gameState.locale</code>; the UI switches via the <code>/set_locale</code> endpoint.

{{Note|Strings missing from the dictionary simply fall through to English, so a partial translation is perfectly valid.

The <code>*-backup-*</code> files in the locale folder are timestamped editing backups and are git-ignored - ignore them.}}

=== In-game hints - <code>resources/app/js/data/hints/</code> ===

The contextual hint system is data-driven. Hint files are grouped by view:

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

Each file exports an array of hint objects:

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

The matcher (<code>js/services/hintMatcher.js</code>) picks the most specific matching hint for the current screen. You can rewrite hint text, add new hints, or retarget <code>match</code> conditions - all without touching engine code.

=== Company names - <code>CORPNAME.DAT</code> (plain text, directly editable) ===

<code>resources/app/CORPNAME.DAT</code> is the company-name database, and unlike most <code>.DAT</code> files it is '''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 symbol | company name</code>.

It is read by the engine's <code>GetCorpNames</code> routine at '''new-game''' time, so edits take effect on the next new game (not on already-saved games). You can rename companies, change ticker symbols, or change a company's home nation.

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

=== Other game-data files (limited / not practical) ===

These ship in <code>resources/app/</code> but are '''not practically moddable''' without the original tooling:

{| class="wikitable"
! File(s) !! Content !! Why limited
|-
| <code>QUOTEWSR.DAT</code> || "Quote of the day" text || Encrypted/encoded; plaintext source is <code>quotehs.prm</code> but the engine reads the encoded <code>.DAT</code>
|-
| <code>MSCNEWS.DAT</code> || News & scenario headline text (hundreds of paragraphs) || Encoded; <code>MSCNEWS.PRM</code> is a near-plaintext source but the engine reads the encoded <code>.DAT</code>
|-
| <code>scenwin1-4.prm</code> || Scenario window text || Engine-internal format
|-
| <code>GAME01.DAT … GAME50.DAT</code> || Save slots / scenario data || Proprietary binary save format
|-
| <code>WSR101.DAT</code>, <code>REGINFO.DAT</code>, etc. || Engine data || Proprietary binary
|}

Treat these as read-only. (Company names are the one genuinely editable game-data file - see [[#Company names - CORPNAME.DAT (plain text, directly editable)|above]].)

== The runtime: how the UI talks to the engine ==

When <code>wsr.exe</code> starts, <code>ui.dll</code> binds a '''REST server''' and a '''WebSocket server''' on OS-assigned ephemeral ports, and writes them to:

<pre>
%LOCALAPPDATA%\Wall Street Raider\runtime.json
{ "pid": 12345, "rest_port": 54321, "ws_port": 54322 }
</pre>

* Electron's main process reads that file and hands the ports to the renderer via the <code>bridge-ports</code> IPC message.
* <code>js/api.js</code> builds <code>http://127.0.0.1:&lt;rest_port&gt;</code> and <code>ws://127.0.0.1:&lt;ws_port&gt;</code> from it.
* The '''WebSocket''' pushes game-state updates (full snapshot on connect, then JSON-patch diffs on <code>/game_state_patch</code>). When WS is connected, HTTP polling is suspended; if WS drops, <code>app.js</code> falls back to polling <code>GET /gamestate</code> (200 ms on the menu, 50 ms in-game).

For a mod, you almost never touch this plumbing directly - you call the functions in <code>api.js</code> and read from the <code>gameStore</code>.

== The API - everything you can make the game do ==

All state-changing actions go through a fixed set of named REST endpoints, each of which the bridge turns into a typed engine event. '''There is no generic "run arbitrary command" endpoint''' - you can only do what an endpoint exists for. The good news: there are ~150 of them, covering every player action in the game.

=== Calling the API from a mod ===

<code>js/api.js</code> already wraps every endpoint in a named async function. Import and call:

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

await api.buyStock(companyId);            // buy
await api.setDividend(actingAsId);        // open the set-dividend flow
await api.merger(targetId, actingAsId);   // start a merger
await api.cheatAddCash();                 // cheat menu: add cash
const state = await api.getGameState();   // full state snapshot
</pre>

Under the hood there are four request shapes (also exported, if you need to hit an endpoint that has no named wrapper yet):

{| class="wikitable"
! Helper !! Body sent !! 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>actingAsId</code> runs the action as a company you control
|-
| <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> || - || <code>GET</code> endpoints
|}

The <code>actingAsId</code> parameter is important: passing the ID of a company you control makes the engine execute the action ''as that company'' (e.g. have a subsidiary buy stock), then restore. <code>0</code> means "as the player."

=== Endpoint reference ===

'''Read (GET):'''

{| class="wikitable"
! Endpoint !! Returns
|-
| <code>/status</code> || health check
|-
| <code>/gamestate</code> || full game-state JSON (see [[#The gameState - everything you can read|§6]])
|-
| <code>/quote</code> || quote of the day
|-
| <code>/asset_chart</code> || price history for an asset
|-
| <code>/database_data</code> || database/search dataset
|-
| <code>/ownership_tree</code> || corporate ownership tree
|-
| <code>/subsidiaries_tree</code> || subsidiary tree
|}

'''Game / session control:''' <code>/newgame</code>, <code>/loadgame</code>, <code>/load_specific_save</code> (str), <code>/savegame</code>, <code>/savegameas</code> (str), <code>/exit_game</code>, <code>/check_scoreboard</code>, <code>/start_ticker</code>, <code>/run_ticker</code>, <code>/stop_ticker</code>, <code>/set_ticker_speed</code> (id), <code>/ticker_advance</code>, <code>/clear_event_string</code>, <code>/splash_screen_played</code>.

'''Trading - stocks & bonds:''' <code>/buy_stock</code>, <code>/sell_stock</code>, <code>/short_stock</code>, <code>/cover_short_stock</code>, <code>/buy_corporate_bond</code>, <code>/sell_corporate_bond</code>, <code>/buy_long_govt_bonds</code>, <code>/sell_long_govt_bonds</code>, <code>/buy_short_govt_bonds</code>, <code>/sell_short_govt_bonds</code>.

'''Trading - commodities & crypto:''' <code>/buy_commodity_futures</code>, <code>/sell_commodity_futures</code>, <code>/close_long_commodity_futures_by_slot</code>, <code>/short_commodity_futures</code>, <code>/cover_short_commodity_futures</code>, <code>/cover_short_commodity_futures_by_slot</code>, <code>/buy_physical_commodity</code>, <code>/sell_physical_commodity</code>, <code>/buy_physical_crypto</code>, <code>/sell_physical_crypto</code>, <code>/buy_crypto_futures</code>, <code>/sell_crypto_futures</code>.

'''Trading - options:''' <code>/buy_calls</code>, <code>/sell_calls</code>, <code>/buy_puts</code>, <code>/sell_puts</code>, <code>/advanced_options_trading</code>, <code>/exercise_call_options_early</code>, <code>/exercise_put_options_early</code>.

'''Corporate management:''' <code>/prepay_taxes</code>, <code>/elect_ceo</code>, <code>/resign_as_ceo</code>, <code>/change_managers</code>, <code>/set_dividend</code>, <code>/set_productivity</code>, <code>/set_growth_rate</code>, <code>/restructure</code>, <code>/buy_corporate_assets</code>, <code>/sell_corporate_assets</code>, <code>/offer_corporate_assets_for_sale</code>, <code>/view_for_sale_items</code>, <code>/sell_subsidiary_stock</code>, <code>/rebrand</code>, <code>/toggle_company_autopilot</code>, <code>/toggle_global_autopilot</code>, <code>/become_etf_advisor</code>, <code>/set_advisory_fee</code>, <code>/decrease_earnings</code>, <code>/increase_earnings</code>.

'''M&A / corporate finance:''' <code>/merger</code>, <code>/greenmail</code>, <code>/lbo</code>, <code>/startup</code>, <code>/capital_contribution</code>, <code>/public_stock_offering</code>, <code>/private_stock_offering</code>, <code>/issue_new_corp_bonds</code>, <code>/redeem_corp_bonds</code>, <code>/extraordinary_dividend</code>, <code>/tax_free_liquidation</code>, <code>/taxable_liquidation</code>, <code>/spin_off</code>, <code>/split_stock</code>, <code>/reverse_split_stock</code>.

'''Banking / loans / swaps:''' <code>/borrow_money</code>, <code>/repay_loan</code>, <code>/advance_funds</code>, <code>/call_in_advance</code>, <code>/interest_rate_swaps</code>, <code>/view_swap_details</code>, <code>/terminate_swap</code>, <code>/set_bank_allocation</code>, <code>/trade_tbills</code>, <code>/list_bank_loans</code>, <code>/change_bank</code>, <code>/call_in_loan</code>, <code>/buy_business_loans</code>, <code>/sell_business_loan</code>, <code>/buy_consumer_loans</code>, <code>/sell_consumer_loans</code>, <code>/buy_prime_mortgages</code>, <code>/sell_prime_mortgages</code>, <code>/buy_subprime_mortgages</code>, <code>/sell_subprime_mortgages</code>, <code>/list_etfs</code>, <code>/freeze_all_loans</code>, <code>/freeze_loan</code>.

'''Legal / dirty tricks:''' <code>/change_law_firm</code>, <code>/antitrust_lawsuit</code>, <code>/harrassing_lawsuit</code>, <code>/spread_rumors</code>.

'''Reports / views / navigation:''' <code>/set_active_ui_report</code> (id), <code>/set_view_asset</code> (id), <code>/set_view_industry</code> (id), <code>/database_search</code>, <code>/clear_chart</code>, <code>/growth_throttle</code>, <code>/clear_stream_list</code>, <code>/fill_stream_list</code>, <code>/toggle_streaming_quote</code> (id), <code>/nav_back</code>, <code>/nav_forward</code>, <code>/nav_clear</code>, <code>/nav_goto</code> (id), plus the market-report triggers <code>/view_current_interest_rates</code>, <code>/whos_ahead</code>, <code>/db_research_tool</code>, <code>/economic_stats</code>, <code>/most_cash_report</code>, <code>/largest_market_cap</code>, <code>/largest_tax_losses</code>, <code>/industry_summary</code>, <code>/industry_projections</code>, <code>/view_corp_assets_for_sale</code>.

'''Settings (toggles):''' <code>/supp_earn_select</code>, <code>/currency_select</code>, <code>/supp_warn_select</code>, <code>/suppress_select</code>, <code>/autosave_select</code>, <code>/exercise_select</code>, <code>/sweep_select</code>, <code>/makedelivery_select</code>, <code>/takedelivery_select</code>, <code>/tooltips_select</code>, <code>/shareholdergraph_select</code>, <code>/disablehotkeys_select</code>, <code>/autoadd_select</code>, <code>/set_chart_type</code> (id), <code>/set_locale</code> (str).

'''Cheat menu:''' <code>/cheat_disable</code>, <code>/cheat_disable_lawsuits</code>, <code>/cheat_merger_info</code>, <code>/cheat_earnings_info</code>, <code>/cheat_add_cash</code>. (These are fixed-function - e.g. <code>/cheat_add_cash</code> adds a preset amount; there is no "set cash to N" endpoint.)

'''Modals:''' <code>/close_modal</code>, <code>/modal_result</code>.

'''Tutorial:''' <code>/set_tutorial_step</code> (id), <code>/set_tutorial_enabled</code> (id).

'''Price alerts:''' <code>/create_price_alert</code>, <code>/show_price_alerts</code>, <code>/delete_price_alert</code>.

'''CustomData:''' <code>/set_custom_data</code> - see [[#The CustomData API - your persistent storage|§7]].

{{Note|<code>js/api.js</code> also exports useful '''ID constants''' so you don't hardcode magic numbers: entity IDs (<code>HUMAN1_ID</code>, <code>COMPUTER1_ID</code>, …), industry indices (<code>BANK_IND</code>, <code>INSURANCE_IND</code>, <code>ETF_IND</code>, …), special asset IDs (<code>OIL_ID</code>, <code>GOLD_ID</code>, <code>BITCOIN_ID</code>, <code>PRIME_RATE_ID</code>, …), and the <code>UI_*</code> report IDs used with <code>/set_active_ui_report</code>.}}

== The gameState - everything you can read ==

<code>GET /gamestate</code> (or <code>api.getGameState()</code>, or the live <code>gameStore</code>) returns a single JSON object - roughly 90 top-level fields - that is the complete read model of the game. In a component, subscribe to just the fields you need so you only re-render on those:

<pre>
import { useGameStore } from '../api.js';
const cash = useGameStore(s => s.gameState.cash);
const year = useGameStore(s => s.gameState.currentYear);
</pre>

Major fields include:

* '''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> (a deep object: cash, assets, debt, equity, EPS, cash-flow, etc.), <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>, and '''<code>customData</code>''' (see [[#The CustomData API - your persistent storage|§7]]).

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

== The CustomData API - 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 just stores it verbatim, writes it into the <code>.WSR</code>/<code>.DAT</code> save on save, and restores it on load. It is exposed back to you 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.

=== Reading ===

<pre>
import { useGameStore } from '../api.js';
const customData = useGameStore(s => s.gameState?.customData ?? {});
const myStuff = customData.myModKey;
</pre>

=== Writing ===

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

Important semantics:

* '''Shallow merge.''' <code>POST /set_custom_data</code> merges your object into the existing <code>customData</code> at the '''top level''' - incoming top-level keys overwrite, other keys are preserved. So namespace your data under one top-level key (e.g. <code>myModKey</code>) and write that whole sub-object each time.
* '''It round-trips.''' After you write, the new value comes back on the next <code>gameState</code> broadcast as <code>gameState.customData</code>.
* '''It is inert.''' The engine does not validate, interpret, or simulate on it. It is pure storage. It cannot be used to change cash, prices, or any engine value - for that you must use the action endpoints in [[#The API - everything you can make the game do|§5]].
* '''It is per-save.''' It is saved and loaded with the game; a fresh "New Game" starts with empty <code>customData</code>.

=== Keys already in use by the base game ===

The stock UI already stores a few things in <code>customData</code> - '''do not reuse these top-level keys''' for your own data:

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

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

== What you cannot do (today) ==

So expectations are clear:

* '''No raw memory / pointer writes.''' The bridge exposes the engine's state through curated endpoints only. You cannot poke an arbitrary game variable from JavaScript - there is no generic "set value X" endpoint. The only free-form write is <code>customData</code>, and it is inert ([[#The CustomData API - your persistent storage|§7]]).
* '''No intercepting the update loop.''' The WebSocket delivers a ''snapshot''. You can read it and react, but you cannot mutate values mid-update or inject into the serialization.
* '''No new engine behavior without recompiling.''' The simulation lives in PowerBASIC (<code>src/main/wsr/*.inc</code>, ~178K lines). Adding a genuinely new game mechanic, a new event type, or a new endpoint means editing that source and rebuilding <code>wsr.exe</code> (PowerBASIC 9.80) and usually <code>ui.dll</code> (Visual Studio C++). That is engine development, not modding.
* '''No editing binary game data.''' Saves and most <code>.DAT</code>/<code>.PRM</code> files are proprietary binary or encoded formats. <code>CORPNAME.DAT</code> (plain text) is the one exception you can safely edit ([[#Company names - CORPNAME.DAT (plain text, directly editable)|§3.7]]).

== Workflow & sharing ==

=== Editing and testing ===

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

=== Packaging a mod for others ===

Because there is no build step, a mod is just '''a set of replacement files'''. The simplest distribution is a zip that mirrors the <code>resources/app/</code> structure, e.g.:

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

with 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, rather than rewriting core files, so two 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 that they should back up originals.

== Quick reference ==

{| 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/feature || New file in <code>js/components/</code>, import it in 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 || Edit <code>CORPNAME.DAT</code> (plain text), starts on next New Game
|-
| Make the game ''do'' something || Call an <code>api.js</code> function ([[#The API - everything you can make the game do|§5]]) - ~150 endpoints
|-
| Read game state || <code>useGameStore(s => s.gameState.&lt;field&gt;)</code> or <code>GET /gamestate</code> ([[#The gameState - everything you can read|§6]])
|-
| Persist my mod's own data in saves || <code>setCustomData({ myKey: … })</code> ([[#The CustomData API - your persistent storage|§7]])
|-
| Change a core simulation rule || Not moddable - requires engine source + recompile
|}

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