> ## 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 prop placer - dependencies, streaming, limits, gizmo, and database

## 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 `spooni_propPlacer` folder to your server's `resources` directory
  </Step>

  <Step title="Configure dependencies">
    Ensure required dependencies are properly configured in your `server.cfg`
  </Step>

  <Step title="Start order">
    Add `ensure spooni_propPlacer` to your `server.cfg` after dependencies
  </Step>
</Steps>

### Dependencies

<AccordionGroup>
  <Accordion title="Required dependencies">
    * **oxmysql**: Database system for persistent storage
    * **Framework**: VORP Core (`vorp_core`, `vorp_inventory`) or RSG Core (`rsg-core`)
  </Accordion>

  <Accordion title="Optional dependencies">
    * **gs\_gizmo**: Enhanced placement gizmo for better UX (recommended)
    * See: [gs\_gizmo repository](https://github.com/GlitchOo/gs_gizmo)
  </Accordion>
</AccordionGroup>

### Recommended start order

```cfg theme={null}
ensure oxmysql
ensure vorp_core          # or rsg-core
ensure vorp_inventory      # if using VORP
ensure gs_gizmo           # optional, for enhanced placement
ensure spooni_propPlacer
```

<Note>
  The SQL table is automatically created on first resource start.
</Note>

## Configuration

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

### Streaming settings

```lua theme={null}
-- Streaming configuration for performance optimization
Config.StreamRadius = 120.0        -- Load props within this distance
Config.DespawnRadius = 140.0       -- Unload beyond this distance
Config.StreamCheckIntervalMs = 1000 -- Streaming tick interval in milliseconds
```

### Removal settings

```lua theme={null}
-- Prop removal configuration
Config.RemoveCommand = 'pickupprop'           -- Command to pick up props
Config.RemoveRadius = 2.5                     -- Distance required to remove props
Config.AllowOwnerOnlyRemoval = true           -- Only owners can remove their props
```

### Limits configuration

```lua theme={null}
-- Placement limits to prevent abuse
Config.MaxItemsPerPlayer = 10  -- Global per-player placement cap
```

### Placeable items

Define which items can be placed as props:

```lua theme={null}
-- Define placeable items and their corresponding props
Config.Placeables = {
    camp_chair = { 
        item = 'campchair', 
        prop = 'p_chair_10x', 
        maxPerPlayer = 3 
    },
    small_crate = { 
        item = 'smallcrate', 
        prop = 'p_crate03x', 
        maxPerPlayer = 5 
    },
    -- Add more placeable items as needed
}
```

### Gizmo configuration

Settings for the placement gizmo (used by `gs_gizmo` if available):

```lua theme={null}
-- Gizmo placement settings
Config.Gizmo = {
    EnableCam = true,           -- Enable camera controls
    MaxDistance = 30,           -- Maximum placement distance
    MaxCamDistance = 40,        -- Maximum camera distance
    MinY = -40,                 -- Minimum Y position
    MaxY = 40,                  -- Maximum Y position
    MovementSpeed = 0.15        -- Movement sensitivity
}
```

## Database structure

Props are persisted in the `prop_placer` table with the following structure:

```sql theme={null}
CREATE TABLE prop_placer (
    id INT AUTO_INCREMENT PRIMARY KEY,
    owner_id VARCHAR(50) NOT NULL,
    placeable_key VARCHAR(50) NOT NULL,
    item_name VARCHAR(50) NOT NULL,
    model VARCHAR(100) NOT NULL,
    x FLOAT NOT NULL,
    y FLOAT NOT NULL,
    z FLOAT NOT NULL,
    rx FLOAT NOT NULL,
    ry FLOAT NOT NULL,
    rz FLOAT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

<Info>
  The table is automatically created on first resource start. No manual database setup required.
</Info>

## Gizmo integration

The script automatically integrates with `gs_gizmo` when available:

<Info>
  When `gs_gizmo` is running, the script provides a polished placement experience with advanced controls and visual feedback.
</Info>

### Gizmo features

* **Intuitive controls**: Mouse and keyboard controls for precise placement
* **Visual feedback**: Real-time preview with proper lighting and shadows
* **Distance limits**: Configurable placement and camera distance limits
* **Smooth movement**: Adjustable movement speed for fine-tuning

### Fallback mode

When `gs_gizmo` is not available, the script falls back to a simpler placement system:

* **Translucent ghost**: Visual preview of the prop
* **Basic controls**: Simple movement and rotation controls
* **Functional placement**: All core features remain available

<Note>
  While the fallback mode works well, using `gs_gizmo` provides a significantly better user experience.
</Note>

## Performance optimization

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

* **Client-side streaming**: Props only load when players are nearby
* **Configurable radii**: Adjust streaming and despawn distances based on your server needs
* **Entity limits**: Prevent excessive prop placement with per-player and per-item limits
* **Safe restarts**: Automatic cleanup prevents duplicate entities after restarts

### Performance tips

* **Stream radius**: Keep `Config.StreamRadius` reasonable (100-150 units)
* **Check interval**: Increase `Config.StreamCheckIntervalMs` for less frequent checks
* **Item limits**: Set appropriate `maxPerPlayer` values for each placeable item
* **Global limits**: Use `Config.MaxItemsPerPlayer` to prevent excessive placement

## Troubleshooting

<AccordionGroup>
  <Accordion title="Item not being removed">
    Ensure `Config.Placeables[...].item` exactly matches your inventory item name. Confirm your framework inventory system is running and supports `getItemCount`/`subItem` functions.
  </Accordion>

  <Accordion title="Props not spawning">
    Double-check model names are valid and loadable on RedM. Verify the prop model exists in your server's stream files.
  </Accordion>

  <Accordion title="Duplicates after restart">
    Ensure the resource is not force-stopped mid-logic. The script automatically triggers client cleanup on stop/restart to prevent duplicates.
  </Accordion>

  <Accordion title="Performance issues">
    Reduce the streaming radius, increase check intervals, lower placement limits, and ensure you're not exceeding server entity limits.
  </Accordion>

  <Accordion title="Gizmo not working">
    Verify `gs_gizmo` is properly installed and started before `spooni_propPlacer`. Check that the resource is running without errors.
  </Accordion>
</AccordionGroup>

## Framework integration

The script includes built-in support for multiple frameworks:

<CodeGroup>
  ```lua VORP Core theme={null}
  -- Automatically detected when vorp_core is running
  -- Requires vorp_inventory for item management
  -- No additional configuration required
  ```

  ```lua RSG Core theme={null}
  -- Automatically detected when rsg-core is running
  -- Uses RSG inventory system for item management
  -- No additional configuration required
  ```

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

## 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="Documentation" icon="book" href="/">
    Docs home - installation basics and links to every script.
  </Card>
</Columns>