# How to add new Shell

This guide explains how to add a new **shell** to RTX Housing System.

Shell definitions are stored in:

```
configs/shells.lua
```

✅ **All coordinates in `Config.HouseShells` are OFFSETS** relative to the shell entity (not world coords).\
For the fastest workflow, we strongly recommend using our **In‑Game Shell Offset Creator**:\
`[Dev Tools - Docs]\rtx_shellcreator`

{% stepper %}
{% step %}

### Install / start your shell resource

* Install your shell resource.
* Make sure the resource is started **before** `rtx_housing` in your `server.cfg`.

Example:

```cfg
ensure my_shell_pack
ensure rtx_housing
```

{% endstep %}

{% step %}

### Add the shell to `Config.HouseShells`

Open:

```
configs/shells.lua
```

Inside `Config.HouseShells = { ... }` add a new entry.

Important rules

* **Key** must be unique (example: `"newshell"`).
* `object` must be a **real object name that exists** in your shell pack.
* All interaction coordinates are **offsets** (use the offset tool to generate them).
* Use `{coords = vector3(0.0, 0.0, 0.0)}` to disable optional points (wardrobe/storage etc.).
* `images` are optional but highly recommended for UI preview.

<details>

<summary><strong>Config fields explained (click to expand)</strong></summary>

* **key**: unique shell identifier (used internally)
* **label**: name shown in UI
* **object**: shell object name to spawn
* **tags**: tags used for filtering (Empty, Furnished, Apartment, House, creator)
* **exitcoords**: exit position inside the shell (coords + heading)
* **managmentcoords**: property management interaction position
* **wardrobecoords**: wardrobe interaction position
* **storagecoords**: storage interaction position
* **cookcoords**: kitchen interaction position (0,0,0 = not available)
* **sinkcoords**: sink interaction positions (water + player coords)
* **showercoords**: shower interaction positions (water + player coords)
* **cleanpoints**: cleaning interaction positions
* **images**: preview images shown in UI

</details>
{% endstep %}

{% step %}

### Copy an existing shell and edit it

The easiest method is to copy our example shell (e.g. `rtx_housing_shell_1`) and paste a new entry below it.

<details>

<summary><strong>Example: Copy &#x26; paste template (click to expand)</strong></summary>

```lua
["newshell"] = {
    label = "New Shell",
    object = "newshellobject",
    tags = {"Empty", "Apartment"},

    exitcoords = {coords = vector3(0.0, 0.0, 0.0), heading = 0.0},
    managmentcoords = {coords = vector3(0.0, 0.0, 0.0)},
    wardrobecoords = {coords = vector3(0.0, 0.0, 0.0)},
    storagecoords = {coords = vector3(0.0, 0.0, 0.0)},
    cookcoords = {coords = vector3(0.0, 0.0, 0.0)},

    sinkcoords = {
        {coordswater = vector3(0.0, 0.0, 0.0), coordsplayer = vector3(0.0, 0.0, 0.0), heading = 0.0},
    },

    showercoords = {
        {coordswater = vector3(0.0, 0.0, 0.0), coordsplayer = vector3(0.0, 0.0, 0.0), heading = 0.0},
    },

    cleanpoints = {
        {coords = vector3(0.0, 0.0, 0.0)},
    },

    images = {
        {url = "img/previewimages/newshell_1.webp"},
        {url = "img/previewimages/newshell_2.webp"},
    },
},
```

</details>
{% endstep %}

{% step %}

### Generate correct offsets with RTX Shell Creator (recommended)

What it does

* The Shell Creator spawns a shell and lets you place interaction points **inside the shell**, then outputs ready‑to‑paste offset data into F8 console.

> ⚠️ This is a **developer tool**. Do **not** run it on a live/public server.

Shell Creator commands

Spawn a shell:

```
/spawnshell shellname
```

Example:

```
/spawnshell shell_michael
```

Add interaction points:

```
/addpoint exit
/addpoint management
/addpoint wardrobe
/addpoint storage
/addpoint cook
/addpoint shower
/addpoint sink
/addpoint clean
```

Noclip (inside shell):

```
/noclipshell
```

Save the output

* All commands will print generated data in **F8 console**.
* Copy the entire output and paste it into your `Config.HouseShells` entry.
  {% endstep %}

{% step %}

### Restart and test

1. Restart the housing resource:

```
restart rtx_housing
```

2. Open Property Creator and create a test property using your new shell.
3. Verify:

* exit works
* management interaction works
* wardrobe/storage points (if enabled) work
* preview images load (if configured)
  {% endstep %}
  {% endstepper %}

{% hint style="warning" %}
Common mistakes:

* ❌ Using an `object` that does not exist (shell will not spawn)
* ❌ Using world coords instead of offsets (interactions will be in wrong positions)
* ❌ Duplicate key in `Config.HouseShells` (only one will load)
  {% endhint %}

## Need help?

If you want, **we can add the shell for you** (including offsets + images).\
Contact us on Discord: <https://discord.gg/rtxdev>