> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dietrich-development.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> Install and configure the Stockmarket script - general settings, admin permissions, commands, and locations

## Installation

<Steps>
  <Step title="Download">
    Get the latest release from our [Tebex store](https://tebex.dietrich-development.com) and download it from your [Keymaster](https://portal.cfx.re/assets/granted-assets)
  </Step>

  <Step title="Extract">
    Extract the script folder to your server's `resources` directory
  </Step>

  <Step title="Configure">
    Add `ensure spooni_stockmarket` to your `server.cfg`
  </Step>

  <Step title="Customize">
    Configure the script to your liking using the configuration options
  </Step>

  <Step title="Restart">
    Restart your server to activate the stock market system
  </Step>
</Steps>

## Configuration

The script is configured through the `config/config_stockmarket.lua` file. Here are the main configuration sections:

### General settings

```lua config.lua theme={null}
Config = {}

Config.debug = false

-- General Settings
Config.General = {
    PriceUpdateInterval = 12, --in hours (and every restart automatically)
    EnableRPEvents = true,
    EnableDividends = true,
    DividendInterval = 3, --how long the holder must hold at least one stock of that company to receive dividends (default 3 days)
    DividendPayoutDay = 15, --day in month
    Language = "en", --must be defined in language.lua
}
```

### Administration settings

```lua config.lua theme={null}
Config.Administration = {
    isAdmin = function(src)
        return IsPlayerAceAllowed(src, "spooni_stockmarket.admin") --in permissions it would look like "add_ace group.admin spooni_stockmarket.admin allow"
    end,
    --if you want to use a custom function to check if a player is admin, you can set it here
    --example:
    --isAdmin = function(src)
    --    return exports['myframework']:IsAdmin(src)
    --end
    -- or with jobs:
    --isAdmin = function(src)
    --    return Bridge.getJob(src) == "police"
    --end
}
```

<Note>
  To set up admin permissions, add the following line to your `server.cfg`:

  ```
  add_ace group.admin spooni_stockmarket.admin allow
  ```
</Note>

### Command configuration

```lua config.lua theme={null}
Config.Commands = {
    enabled = true, --enable commands (set to false if you dont want players to access it everywhere via command)
    onlyAdmin = true, -- if true, only admins can use the command
    openStockmarketCommand = "stockmarket", --open stockmarket 
}
```

### Location-based access

```lua config.lua theme={null}
--if you want to use locations to open the stockmarket, you can set them here (leave Config.Locations empty if you dont want to use locations)
Config.useLocationNames = false --if you want to use the name of the location as Title of the Stockmarket
Config.PromptKey = 0x760A9C6F --key to open the stockmarket
Config.Locations = {
    SaintDenis = {
        name = "Saint Denis Stockmarket",
        blipsprite = 249721687, --set to false if you dont want a blip
        coords = vector3(2651.8323, -1292.5818, 52.2455),
        distance = 2.0,
        jobs = {"police"}, --if you want to joblock it, set it here otherwise leave empty
    }
}
```

<Info>
  The prompt key `0x760A9C6F` corresponds to the `G` key. You can change this to any other key code as needed.
</Info>

## Database setup

The database is created automatically when the resource is started. The system includes the following tables:

* **stocks**: Stock definitions and configuration
* **player\_portfolios**: Player investment tracking
* **transactions**: Trade history and audit trail
* **dividends**: Dividend payout records

<Note>
  The database structure is automatically managed by the script. No manual database setup is required.
</Note>

## Sample stocks

Here are 5 sample stocks you can add to your database after starting the script for the first time:

```sql theme={null}
INSERT INTO `stocks` (`id`, `label`, `description`, `base_price`, `volatility`, `type`, `item_name`, `item_enabled`, `realtime_source`, `realtime_symbol`, `realtime_weight`, `random_enabled`, `random_weight`, `random_max_change`, `custom_weight`, `rp_events_enabled`, `dividends_enabled`, `dividends_mode`, `dividends_amount`, `dividends_percent`, `enabled`) VALUES
	('AMCO', 'Annesburg Mining', 'Industrial mining operations', 45, 1, 'mixed', 'stock_amco', 0, NULL, 'NVDA', 1, 1, 1, 3, 0, 1, 1, 'fixed', 2, 0, 1),
	('BWTC', 'Blackwater Trading Co.', 'Merchants and traders since 1878', 85, 1, 'mixed', 'stock_bwtc', 0, NULL, 'AMZN', 1, 1, 1, 3, 0, 1, 1, 'percent', 0, 1, 1),
	('SDBT', 'Saint Denis Bank & Trust', 'Leading financial institution in Lemoyne', 250, 1, 'mixed', 'stock_sdbt', 0, NULL, 'BRK.B', 1, 1, 1, 3, 0, 1, 1, 'percent', 0, 1, 1),
	('STLB', 'Strawberry Lumber', 'Premium timber and wood products', 60, 1, 'mixed', 'stock_stlb', 0, NULL, 'AAPL', 1, 1, 1, 3, 0, 1, 1, 'percent', 0, 1.8, 1),
	('VCC', 'Valentine Coal Co.', 'Mining company based in the Heartlands', 100, 1, 'mixed', 'stock_vcc', 0, NULL, 'TSLA', 1, 1, 1, 3, 0, 1, 1, 'percent', 0, 2.5, 1);
```

## Real-time stock symbols

You can choose from over 100 real-world stock symbols. Here are some popular options:

<AccordionGroup>
  <Accordion title="Technology stocks">
    AAPL, MSFT, GOOGL, GOOG, NVDA, META, TSLA, ADBE, CRM, INTC, QCOM, IBM, ORCL, NOW, PANW
  </Accordion>

  <Accordion title="Financial stocks">
    BRK.B, JPM, V, MA, BAC, WFC, GS, C, MS, SCHW, AXP, BLK, SPGI, CB, MMC
  </Accordion>

  <Accordion title="Healthcare stocks">
    UNH, JNJ, PFE, LLY, ABBV, MRK, ABT, TMO, DHR, BMY, GILD, MDT, SYK, ISRG, VRTX
  </Accordion>

  <Accordion title="Consumer stocks">
    AMZN, HD, WMT, MCD, SBUX, TGT, TJX, COST, MCD, DIS, NFLX, NKE, PM, MO
  </Accordion>

  <Accordion title="Energy and industrial">
    XOM, CVX, COP, NEE, DUK, SO, CAT, LMT, RTX, NOC, HON, DE, UPS, FDX
  </Accordion>
</AccordionGroup>

<Note>
  To request specific stock symbols or get the complete list, please visit our Discord server.
</Note>

## Framework integration

The script includes built-in support for multiple frameworks:

<CodeGroup>
  ```lua VORP Core theme={null}
  -- Automatically detected when vorp_core is running
  -- No additional configuration required
  -- Uses VORP's database and player management systems
  ```

  ```lua RSG Core theme={null}
  -- Automatically detected when rsg-core is running
  -- No additional configuration required
  -- Uses RSG's database and player management systems
  ```

  ```lua Custom Framework theme={null}
  -- Set in config.lua
  Config.Framework = 'custom'

  -- Requires additional configuration in frameworkBridge.lua
  -- See framework bridge documentation for details
  ```
</CodeGroup>

## Performance considerations

<Info>
  The script is optimized for performance with several key features:
</Info>

* **Efficient database queries**: Optimized database operations for large datasets
* **Configurable update intervals**: Control how often prices update to balance accuracy and performance
* **Caching system**: Price data is cached to reduce API calls
* **Batch processing**: Multiple operations are processed in batches

### Performance tips

* **Update intervals**: Set appropriate price update intervals (12 hours recommended)
* **Stock count**: Limit the number of active stocks to essential ones
* **API limits**: Be mindful of real-time API rate limits
* **Database maintenance**: Regularly clean old transaction records

## Troubleshooting

<AccordionGroup>
  <Accordion title="Stocks not updating">
    Check the price update interval configuration, verify API connections for real-time stocks, and ensure the script is properly started in server.cfg.
  </Accordion>

  <Accordion title="Real-time data not working">
    Verify API credentials are correct, check network connectivity, and ensure the stock symbol is valid and supported.
  </Accordion>

  <Accordion title="Dividends not paying">
    Check dividend configuration settings, verify the payout day is set correctly, and ensure dividends are enabled for the specific stock.
  </Accordion>

  <Accordion title="Player portfolios not saving">
    Verify database connectivity, check for database errors in console, and ensure the database tables were created properly.
  </Accordion>

  <Accordion title="RP events not affecting prices">
    Confirm RP events are enabled in configuration, check event trigger conditions, and verify the event system is properly integrated.
  </Accordion>

  <Accordion title="Admin commands not working">
    Verify admin permissions are set correctly in server.cfg and check the isAdmin function configuration in config.lua.
  </Accordion>

  <Accordion title="Location access not working">
    Check the coordinates and distance settings in Config.Locations, verify the prompt key is correct, and ensure the location is properly configured.
  </Accordion>
</AccordionGroup>

## Support

If you encounter issues or need assistance:

<Columns cols={2}>
  <Card title="Discord support" icon="discord" href="https://discord.gg/4jhQsPr6pe">
    Join our Discord community for support and updates.
  </Card>

  <Card title="Developer reference" icon="book" href="/scripts/stockmarket/developers">
    API details and configuration hooks for this script.
  </Card>
</Columns>