# Catalog Database Reference

> **⚠️ BETA — Not production ready.** This catalog system is still in active development. Schema changes, missing features, and breaking changes may occur.

This document describes the core catalog tables (`catalog_items`, `catalog_pages`, `items_base`) and their compatibility across the Habbo retro stack.

## Overview

The catalog system consists of three core database tables shared between the **emulator (Arcturus Morningstar Extended)**, **Nitro-V3 (React client)**, and **Nitro_Render_V3 (renderer)**:

```
items_base        → defines every furniture item (interaction type, dimensions, stack behavior, etc.)
catalog_pages     → defines the catalog tree structure (pages, sub-pages, layouts)
catalog_items     → defines what items are sold on which pages and at what price
```

Additional tables for special catalog features:
- `catalog_pages_bc` / `catalog_items_bc` — Builders Club catalog
- `catalog_items_limited` — tracks limited-edition (RARE) item sales
- `catalog_club_offers` — HC/VIP/BC subscription offers
- `catalog_clothing` — wearable clothing items
- `catalog_featured_pages` — front page featured slots
- `catalog_target_offers` — targeted promotional offers

## Table Schemas

### `items_base`

Defines the base properties of every furniture item. Referenced by `catalog_items.item_ids`, `items.id`, and many other tables via foreign key.

| Column | Type | Description |
|--------|------|-------------|
| `id` | `int(10) unsigned` | Primary key, matches sprite ID in FurnitureData |
| `sprite_id` | `int(11)` | Sprite identifier (usually same as `id`) |
| `public_name` | `varchar(56)` | Display name shown in the client |
| `item_name` | `varchar(70)` | Internal classname (matches FurnitureData classname) |
| `type` | `varchar(3)` | `s` = floor item, `i` = wall item, `r` = robot/bot, `e` = effect |
| `width` | `int(11)` | Tile width |
| `length` | `int(11)` | Tile length |
| `stack_height` | `double(4,2)` | Stack height (0.00 = flat, 1.00 = normal stack) |
| `allow_stack` | `tinyint(1)` | Can other items be stacked on top |
| `allow_sit` | `tinyint(1)` | Can avatars sit on this |
| `allow_lay` | `tinyint(1)` | Can avatars lay on this |
| `allow_walk` | `tinyint(1)` | Can avatars walk through this |
| `allow_gift` | `tinyint(1)` | Can this be wrapped as a gift |
| `allow_trade` | `tinyint(1)` | Can players trade this |
| `allow_recycle` | `tinyint(1)` | Can this be recycled |
| `allow_marketplace_sell` | `tinyint(1)` | Can this be sold on the marketplace |
| `allow_inventory_stack` | `tinyint(1)` | Does this stack in inventory |
| `interaction_type` | `varchar(500)` | Behavior type (e.g. `default`, `gate`, `teleport`, `wired_trigger`, `dimmer`, `postit`, `bed`, `chair`, `football_counter`, etc.) |
| `interaction_modes_count` | `int(11)` | Number of interaction states (e.g. 2 for toggleable items) |
| `vending_ids` | `varchar(255)` | Vending machine reward item IDs |
| `multiheight` | `varchar(50)` | Multi-height stack data |
| `customparams` | `varchar(256)` | Custom parameters (e.g. clothing set IDs) |
| `effect_id_male` | `int(11)` | Male avatar effect ID |
| `effect_id_female` | `int(11)` | Female avatar effect ID |
| `clothing_on_walk` | `varchar(255)` | Clothing effect applied on walk |

### `catalog_pages`

Defines the hierarchical catalog tree structure visible in the Nitro client.

| Column | Type | Description |
|--------|------|-------------|
| `id` | `int(11)` | Primary key |
| `parent_id` | `int(11)` | Parent page ID (`-1` = root page) |
| `caption_save` | `varchar(25)` | Internal caption key |
| `caption` | `varchar(128)` | Display caption |
| `page_layout` | `enum` | Layout type: `default_3x3`, `frontpage`, `club_buy`, `club_gift`, `spaces`, `spaces_new`, `recycler`, `trophies`, `plasto`, `soundmachine`, `guilds`, `guild_furni`, `bots`, `pets`, `single_bundle`, `productpage1`, `room_bundle`, `sold_ltd_items`, `badge_display`, `vip_buy`, `default_3x3_color_grouping`, `frontpage_featured`, `petcustomization`, `collectibles`, `info_duckets`, `info_rentables`, `info_pets`, `recent_purchases`, `marketplace`, `marketplace_own_items`, `roomads`, `guild_forum`, `info_loyalty`, `loyalty_vip_buy` |
| `icon_color` | `int(11)` | Catalog icon color (1-255) |
| `icon_image` | `int(11)` | Catalog icon image ID |
| `min_rank` | `int(11)` | Minimum rank to view |
| `order_num` | `int(11)` | Sort order |
| `visible` | `enum('0','1')` | Is the page visible |
| `enabled` | `enum('0','1')` | Is the page enabled |
| `club_only` | `enum('0','1')` | HC/VIP only |
| `vip_only` | `enum('1','0')` | VIP only |
| `page_headline` | `varchar(1024)` | Headline image/text key |
| `page_teaser` | `varchar(64)` | Teaser image key |
| `page_special` | `varchar(2048)` | Special layout data |
| `page_text1` | `text` | Primary page text |
| `page_text2` | `text` | Secondary page text |
| `page_text_details` | `text` | Detail text |
| `page_text_teaser` | `text` | Teaser text |
| `room_id` | `int(11)` | Room ID (for room bundle pages) |
| `includes` | `varchar(128)` | Sem colon separated page IDs to include (`1;2;3`) |
| `catalog_mode` | `enum('NORMAL','BUILDER','BOTH')` | Catalog mode |

### `catalog_items`

Links items_base entries to catalog_pages with pricing and availability.

| Column | Type | Description |
|--------|------|-------------|
| `id` | `int(11)` | Primary key |
| `item_ids` | `varchar(666)` | Comma-separated items_base IDs (usually single ID) |
| `page_id` | `int(11)` | FK → catalog_pages.id |
| `offer_id` | `int(11)` | Offer ID (`-1` = default) |
| `song_id` | `int(10) unsigned` | Trax song ID |
| `order_number` | `int(11)` | Sort order within the page |
| `catalog_name` | `varchar(100)` | Catalog name / offer identifier |
| `cost_credits` | `int(11)` | Credit cost |
| `cost_points` | `int(11)` | Points/currency cost |
| `points_type` | `int(11)` | 0 = duckets, 5 = diamonds, others = seasonal currencies |
| `amount` | `int(11)` | Amount received per purchase |
| `limited_sells` | `int(11)` | How many have been sold (auto-tracked) |
| `limited_stack` | `int(11)` | Total limited quantity (0 = unlimited) |
| `extradata` | `varchar(500)` | Extra data (e.g. badge code, preset data) |
| `badge` | `varchar(500)` | Badge code (AtomCMS extension, always null for emulator) |
| `have_offer` | `enum('0','1')` | Is the offer active |
| `club_only` | `enum('0','1')` | HC/VIP only |
| `rate` | `varchar(255)` | Rate info (AtomCMS extension, always null for emulator) |

## Compatibility Matrix

### Emulator (Arcturus Morningstar Extended)

| Table | Status | Notes |
|-------|--------|-------|
| `items_base` | ✅ Full native | The emulator reads this directly for furniture definitions. Full schema match. |
| `catalog_pages` | ✅ Full native | The emulator reads from this for catalog tree. Full schema match. |
| `catalog_items` | ✅ Full native | The emulator reads this for offers/pricing. Full schema match. |

The emulator directly queries all three tables via its DAO layer. No translation or mapping layer is needed.

### Nitro-V3 (React Client)

| Table | Status | Notes |
|-------|--------|-------|
| `items_base` | ✅ Full native via emulator | Client never reads DB directly. Data flows: DB → emulator → Nitro protocol → client. `public_name` is used by `FurniEditor` (see `src/hooks/furni-editor/useFurniEditor.ts:11`). |
| `catalog_pages` | ✅ Full native via emulator | Catalog tree is served by the emulator through `CatalogModeComposer` / `CatalogPageComposer` protocol messages. |
| `catalog_items` | ✅ Full native via emulator | Offer data is served by the emulator through `CatalogOfferComposer` protocol messages. |

The client does not require any direct database access. All catalog data is served real-time via the emulator's Nitro WebSocket protocol.

### Nitro_Render_V3 (Renderer)

| Table | Status | Notes |
|-------|--------|-------|
| `items_base` | ✅ Compatible via client | The renderer receives furniture rendering data (dimensions, interaction type, states) from the client, which receives it from the emulator. |
| `catalog_pages` | ✅ Not applicable | The renderer does not deal with catalog pages. |
| `catalog_items` | ✅ Not applicable | The renderer does not deal with catalog offers. |

The renderer consumes FurnitureData.json (gamedata) for sprite/asset mapping. The `items_base.interaction_type` must match the interaction logic in the renderer's room engine.

## Schema Differences

The AtomCMS schema has two extra columns on `catalog_items` compared to the emulator's reference schema:

| Column | AtomCMS | Emulator | Impact |
|--------|---------|----------|--------|
| `badge` | `varchar(500)` | Not present | Backward compatible — extra column ignored by emulator |
| `rate` | `varchar(255)` | Not present | Backward compatible — extra column ignored by emulator |
| `PRIMARY KEY` | `(id, extradata)` | `(id)` | AtomCMS composite PK does not break emulator FK constraints (`fk_catitems_page` references `page_id`) |

These are safe additions. The emulator only reads the columns it knows about.

## Data Flow

```
┌──────────────┐     SQL      ┌──────────────┐   Nitro Protocol   ┌──────────┐   Render Cmds   ┌────────────────┐
│  MySQL/Maria │ ◄──────────► │  Emulator    │ ◄────────────────► │ Nitro-V3 │ ◄──────────────► │ Nitro_Render_V3│
│  (items_base,│              │  (Arcturus   │   (WebSocket)      │  (React)  │                  │  (PixiJS)      │
│   catalog_*, │              │   Morningstar│                    │           │                  │                │
│   ...)       │              │   Extended)  │                    │           │                  │                │
└──────────────┘              └──────────────┘                    └──────────┘                  └────────────────┘
```

## Reference Data

The FullDatabase.sql shipped with the emulator contains:
- ~10,420 `items_base` rows
- ~769 `catalog_pages` rows
- ~10,790 `catalog_items` rows

This is the beta catalog for Arcturus Morningstar Extended, compatible with Nitro-V3 and Nitro_Render_V3. Not yet production-ready — expect ongoing changes.

## See Also

- `/var/www/emulator/Default Database/FullDatabase.sql` — reference database
- `/var/www/emulator/docs/builders_club_catalog_reference.md` — BC catalog docs
- `/var/www/atomcms/database/schema/mysql-schema.sql` — AtomCMS schema
- `/var/www/atomcms/app/Services/CatalogService.php` — CMS catalog sync tools
- `/var/www/Nitro-V3/src/hooks/furni-editor/useFurniEditor.ts` — client furni editor