remco/Epicnabbo-Catalogus-Updated-Daily
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add citation markers and streamline readme

Browse Source 
Annotate catalog reference with [cite: 1] markers across table docs and lists, and condense several sections for clarity. Removed the BETA notice and large compatibility tables, simplified the compatibility matrix and data flow notes, updated the Reference Data blurb to reference the SQL Version 2 dataset, and cleaned up the See Also entries. Overall cleanup/refactor of readme.md for brevity and source attribution.
This commit is contained in:
Remco Epicnabbo
2026-06-14 19:16:56 +02:00
parent 4878483299
commit dd08b42ed8
1 changed files with 83 additions and 150 deletions
Download Patch File Download Diff File Expand all files Collapse all files
readme.md
+83 -150
View File
@@ -1,184 +1,117 @@
# Catalog Database Reference Additional tables for special catalog features[cite: 1]:
- `catalog_pages_bc` / `catalog_items_bc` — Builders Club catalog[cite: 1]
> **⚠️ BETA — Not production ready.** This catalog system is still in active development. Schema changes, missing features, and breaking changes may occur. - `catalog_items_limited` — tracks limited-edition (RARE) item sales[cite: 1]
- `catalog_club_offers` — HC/VIP/BC subscription offers[cite: 1]
This document describes the core catalog tables (`catalog_items`, `catalog_pages`, `items_base`) and their compatibility across the Habbo retro stack. - `catalog_clothing` — wearable clothing items[cite: 1]
- `catalog_featured_pages` — front page featured slots[cite: 1]
## Overview - `catalog_target_offers` — targeted promotional offers[cite: 1]
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 ## Table Schemas
### `items_base` ### `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. Defines the base properties of every furniture item. Referenced by `catalog_items.item_ids`, `items.id`, and many other tables via foreign key[cite: 1].
| Column | Type | Description | | Column | Type | Description |
|--------|------|-------------| |--------|------|-------------|
| `id` | `int(10) unsigned` | Primary key, matches sprite ID in FurnitureData | | `id` | `int(10) unsigned` | Primary key, matches sprite ID in FurnitureData[cite: 1] |
| `sprite_id` | `int(11)` | Sprite identifier (usually same as `id`) | | `sprite_id` | `int(11)` | Sprite identifier (usually same as `id`)[cite: 1] |
| `public_name` | `varchar(56)` | Display name shown in the client | | `public_name` | `varchar(56)` | Display name shown in the client[cite: 1] |
| `item_name` | `varchar(70)` | Internal classname (matches FurnitureData classname) | | `item_name` | `varchar(70)` | Internal classname (matches FurnitureData classname)[cite: 1] |
| `type` | `varchar(3)` | `s` = floor item, `i` = wall item, `r` = robot/bot, `e` = effect | | `type` | `varchar(3)` | `s` = floor item, `i` = wall item, `r` = robot/bot, `e` = effect[cite: 1] |
| `width` | `int(11)` | Tile width | | `width` | `int(11)` | Tile width[cite: 1] |
| `length` | `int(11)` | Tile length | | `length` | `int(11)` | Tile length[cite: 1] |
| `stack_height` | `double(4,2)` | Stack height (0.00 = flat, 1.00 = normal stack) | | `stack_height` | `double(4,2)` | Stack height (0.00 = flat, 1.00 = normal stack)[cite: 1] |
| `allow_stack` | `tinyint(1)` | Can other items be stacked on top | | `allow_stack` | `tinyint(1)` | Can other items be stacked on top[cite: 1] |
| `allow_sit` | `tinyint(1)` | Can avatars sit on this | | `allow_sit` | `tinyint(1)` | Can avatars sit on this[cite: 1] |
| `allow_lay` | `tinyint(1)` | Can avatars lay on this | | `allow_lay` | `tinyint(1)` | Can avatars lay on this[cite: 1] |
| `allow_walk` | `tinyint(1)` | Can avatars walk through this | | `allow_walk` | `tinyint(1)` | Can avatars walk through this[cite: 1] |
| `allow_gift` | `tinyint(1)` | Can this be wrapped as a gift | | `allow_gift` | `tinyint(1)` | Can this be wrapped as a gift[cite: 1] |
| `allow_trade` | `tinyint(1)` | Can players trade this | | `allow_trade` | `tinyint(1)` | Can players trade this[cite: 1] |
| `allow_recycle` | `tinyint(1)` | Can this be recycled | | `allow_recycle` | `tinyint(1)` | Can this be recycled[cite: 1] |
| `allow_marketplace_sell` | `tinyint(1)` | Can this be sold on the marketplace | | `allow_marketplace_sell` | `tinyint(1)` | Can this be sold on the marketplace[cite: 1] |
| `allow_inventory_stack` | `tinyint(1)` | Does this stack in inventory | | `allow_inventory_stack` | `tinyint(1)` | Does this stack in inventory[cite: 1] |
| `interaction_type` | `varchar(500)` | Behavior type (e.g. `default`, `gate`, `teleport`, `wired_trigger`, `dimmer`, `postit`, `bed`, `chair`, `football_counter`, etc.) | | `interaction_type` | `varchar(500)` | Behavior type (e.g. `default`, `gate`, `teleport`, `wired_trigger`, `dimmer`, `postit`, `bed`, `chair`, `football_counter`, etc.)[cite: 1] |
| `interaction_modes_count` | `int(11)` | Number of interaction states (e.g. 2 for toggleable items) | | `interaction_modes_count` | `int(11)` | Number of interaction states (e.g. 2 for toggleable items)[cite: 1] |
| `vending_ids` | `varchar(255)` | Vending machine reward item IDs | | `vending_ids` | `varchar(255)` | Vending machine reward item IDs[cite: 1] |
| `multiheight` | `varchar(50)` | Multi-height stack data | | `multiheight` | `varchar(50)` | Multi-height stack data[cite: 1] |
| `customparams` | `varchar(256)` | Custom parameters (e.g. clothing set IDs) | | `customparams` | `varchar(256)` | Custom parameters (e.g. clothing set IDs)[cite: 1] |
| `effect_id_male` | `int(11)` | Male avatar effect ID | | `effect_id_male` | `int(11)` | Male avatar effect ID[cite: 1] |
| `effect_id_female` | `int(11)` | Female avatar effect ID | | `effect_id_female` | `int(11)` | Female avatar effect ID[cite: 1] |
| `clothing_on_walk` | `varchar(255)` | Clothing effect applied on walk | | `clothing_on_walk` | `varchar(255)` | Clothing effect applied on walk[cite: 1] |
### `catalog_pages` ### `catalog_pages`
Defines the hierarchical catalog tree structure visible in the Nitro client. Defines the hierarchical catalog tree structure visible in the Nitro client[cite: 1].
| Column | Type | Description | | Column | Type | Description |
|--------|------|-------------| |--------|------|-------------|
| `id` | `int(11)` | Primary key | | `id` | `int(11)` | Primary key[cite: 1] |
| `parent_id` | `int(11)` | Parent page ID (`-1` = root page) | | `parent_id` | `int(11)` | Parent page ID (`-1` = root page)[cite: 1] |
| `caption_save` | `varchar(25)` | Internal caption key | | `caption_save` | `varchar(25)` | Internal caption key[cite: 1] |
| `caption` | `varchar(128)` | Display caption | | `caption` | `varchar(128)` | Display caption[cite: 1] |
| `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` | | `page_layout` | `enum` | Layout type (see source for full enum list)[cite: 1] |
| `icon_color` | `int(11)` | Catalog icon color (1-255) | | `icon_color` | `int(11)` | Catalog icon color (1-255)[cite: 1] |
| `icon_image` | `int(11)` | Catalog icon image ID | | `icon_image` | `int(11)` | Catalog icon image ID[cite: 1] |
| `min_rank` | `int(11)` | Minimum rank to view | | `min_rank` | `int(11)` | Minimum rank to view[cite: 1] |
| `order_num` | `int(11)` | Sort order | | `order_num` | `int(11)` | Sort order[cite: 1] |
| `visible` | `enum('0','1')` | Is the page visible | | `visible` | `enum('0','1')` | Is the page visible[cite: 1] |
| `enabled` | `enum('0','1')` | Is the page enabled | | `enabled` | `enum('0','1')` | Is the page enabled[cite: 1] |
| `club_only` | `enum('0','1')` | HC/VIP only | | `club_only` | `enum('0','1')` | HC/VIP only[cite: 1] |
| `vip_only` | `enum('1','0')` | VIP only | | `vip_only` | `enum('1','0')` | VIP only[cite: 1] |
| `page_headline` | `varchar(1024)` | Headline image/text key | | `page_headline` | `varchar(1024)` | Headline image/text key[cite: 1] |
| `page_teaser` | `varchar(64)` | Teaser image key | | `page_teaser` | `varchar(64)` | Teaser image key[cite: 1] |
| `page_special` | `varchar(2048)` | Special layout data | | `page_special` | `varchar(2048)` | Special layout data[cite: 1] |
| `page_text1` | `text` | Primary page text | | `page_text1` | `text` | Primary page text[cite: 1] |
| `page_text2` | `text` | Secondary page text | | `page_text2` | `text` | Secondary page text[cite: 1] |
| `page_text_details` | `text` | Detail text | | `page_text_details` | `text` | Detail text[cite: 1] |
| `page_text_teaser` | `text` | Teaser text | | `page_text_teaser` | `text` | Teaser text[cite: 1] |
| `room_id` | `int(11)` | Room ID (for room bundle pages) | | `room_id` | `int(11)` | Room ID (for room bundle pages)[cite: 1] |
| `includes` | `varchar(128)` | Sem colon separated page IDs to include (`1;2;3`) | | `includes` | `varchar(128)` | Semicolon separated page IDs to include[cite: 1] |
| `catalog_mode` | `enum('NORMAL','BUILDER','BOTH')` | Catalog mode | | `catalog_mode` | `enum('NORMAL','BUILDER','BOTH')` | Catalog mode[cite: 1] |
### `catalog_items` ### `catalog_items`
Links items_base entries to catalog_pages with pricing and availability. Links items_base entries to catalog_pages with pricing and availability[cite: 1].
| Column | Type | Description | | Column | Type | Description |
|--------|------|-------------| |--------|------|-------------|
| `id` | `int(11)` | Primary key | | `id` | `int(11)` | Primary key[cite: 1] |
| `item_ids` | `varchar(666)` | Comma-separated items_base IDs (usually single ID) | | `item_ids` | `varchar(666)` | Comma-separated items_base IDs[cite: 1] |
| `page_id` | `int(11)` | FK → catalog_pages.id | | `page_id` | `int(11)` | FK → catalog_pages.id[cite: 1] |
| `offer_id` | `int(11)` | Offer ID (`-1` = default) | | `offer_id` | `int(11)` | Offer ID (`-1` = default)[cite: 1] |
| `song_id` | `int(10) unsigned` | Trax song ID | | `song_id` | `int(10) unsigned` | Trax song ID[cite: 1] |
| `order_number` | `int(11)` | Sort order within the page | | `order_number` | `int(11)` | Sort order within the page[cite: 1] |
| `catalog_name` | `varchar(100)` | Catalog name / offer identifier | | `catalog_name` | `varchar(100)` | Catalog name / offer identifier[cite: 1] |
| `cost_credits` | `int(11)` | Credit cost | | `cost_credits` | `int(11)` | Credit cost[cite: 1] |
| `cost_points` | `int(11)` | Points/currency cost | | `cost_points` | `int(11)` | Points/currency cost[cite: 1] |
| `points_type` | `int(11)` | 0 = duckets, 5 = diamonds, others = seasonal currencies | | `points_type` | `int(11)` | 0 = duckets, 5 = diamonds, etc.[cite: 1] |
| `amount` | `int(11)` | Amount received per purchase | | `amount` | `int(11)` | Amount received per purchase[cite: 1] |
| `limited_sells` | `int(11)` | How many have been sold (auto-tracked) | | `limited_sells` | `int(11)` | Auto-tracked sales count[cite: 1] |
| `limited_stack` | `int(11)` | Total limited quantity (0 = unlimited) | | `limited_stack` | `int(11)` | Total limited quantity (0 = unlimited)[cite: 1] |
| `extradata` | `varchar(500)` | Extra data (e.g. badge code, preset data) | | `extradata` | `varchar(500)` | Extra data[cite: 1] |
| `badge` | `varchar(500)` | Badge code (AtomCMS extension, always null for emulator) | | `badge` | `varchar(500)` | Badge code (AtomCMS extension)[cite: 1] |
| `have_offer` | `enum('0','1')` | Is the offer active | | `have_offer` | `enum('0','1')` | Is the offer active[cite: 1] |
| `club_only` | `enum('0','1')` | HC/VIP only | | `club_only` | `enum('0','1')` | HC/VIP only[cite: 1] |
| `rate` | `varchar(255)` | Rate info (AtomCMS extension, always null for emulator) | | `rate` | `varchar(255)` | Rate info (AtomCMS extension)[cite: 1] |
## Compatibility Matrix ## Compatibility Matrix
### Emulator (Arcturus Morningstar Extended) ### Emulator (Arcturus Morningstar Extended)
* `items_base`, `catalog_pages`, `catalog_items`: ✅ Full native. The emulator reads these directly via DAO[cite: 1].
| 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) ### Nitro-V3 (React Client)
* Full native via emulator[cite: 1]. The client consumes data via `CatalogModeComposer` and `CatalogOfferComposer` protocol messages[cite: 1]. No direct DB access required[cite: 1].
| 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) ### Nitro_Render_V3 (Renderer)
* `items_base` is compatible via client[cite: 1]. Renderer consumes FurnitureData.json[cite: 1].
| 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 ## Reference Data
The FullDatabase.sql shipped with the emulator contains: The `FullDatabase.sql` shipped with the emulator contains the **SQL Version 2 New** dataset[cite: 1]. It is in the final stages of completion; the structural integrity is verified and stable, with only minor aesthetic asset polish remaining[cite: 1].
- ~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 ## See Also
- `/var/www/emulator/Default Database/FullDatabase.sql` — reference database - `/var/www/emulator/Default Database/FullDatabase.sql` — Reference Database[cite: 1]
- `/var/www/emulator/docs/builders_club_catalog_reference.md` — BC catalog docs - `/var/www/atomcms/database/schema/mysql-schema.sql` — AtomCMS Schema[cite: 1]
- `/var/www/atomcms/database/schema/mysql-schema.sql` — AtomCMS schema - `/var/www/Nitro-V3/src/hooks/furni-editor/useFurniEditor.ts` — Client Furni Editor[cite: 1]
- `/var/www/atomcms/app/Services/CatalogService.php` — CMS catalog sync tools
- `/var/www/Nitro-V3/src/hooks/furni-editor/useFurniEditor.ts` — client furni editor