Replace README with catalog DB reference

Replace previous EpicNabbo v2 development README with a comprehensive Catalog Database Reference. The new document details core tables (items_base, catalog_pages, catalog_items), additional catalog tables, full column schemas, compatibility with Arcturus emulator, Nitro-V3 client and Nitro_Render_V3 renderer, schema differences, data flow diagram, and reference counts from FullDatabase.sql. Removes the prior development warning/marketing content and provides actionable technical documentation and links to relevant files for developers.
2026-06-11 16:11:52 +02:00
parent 80c40ca6c4
commit 9a3fa1eb6b
1 changed files with 148 additions and 61 deletions
@@ -1,95 +1,182 @@
-# EpicNabbo Catalogue v2 (Development 🛠️)
+# Catalog Database Reference
-EpicNabbo Catalogue v2 is a heavily optimized evolution of our catalog system, specifically engineered for **Nitro v3** with 100% native support.
+This document describes the core catalog tables (`catalog_items`, `catalog_pages`, `items_base`) and their compatibility across the Habbo retro stack.
-> 🔴 **CRITICAL WARNING: DEVELOPMENT ONLY**
+## Overview
 > **DO NOT USE THIS IN A PRODUCTION ENVIRONMENT.** This system currently contains severe bugs that **can wipe your entire database**. It is strictly intended for local development and testing purposes only.
---
+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)**:
-## 🚀 Key Improvements & Objectives
+```
 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
 ```
-* **Massive 52k+ Furni Database:** An increase of over 21,000 items compared to the internal v1 prototype, optimized for high-performance indexing.
+Additional tables for special catalog features:
-* **Native Nitro v3 Support:** Tailored to support all modern Nitro UI elements and packet structures.
+- `catalog_pages_bc` / `catalog_items_bc` — Builders Club catalog
-* **High Quality Standards:** Re-engineered framework to eliminate the performance bottlenecks found during internal testing of the previous unreleased version.
+- `catalog_items_limited` — tracks limited-edition (RARE) item sales
-* **100% Verified Layout:** Merging development data into a superior base ensures zero missing pages or broken assets.
+- `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
-## 📈 Version Compression & Comparison
+### `items_base`
-| Feature | Version 1 (Internal Build) | Version 2 (New Overhaul) |
+Defines the base properties of every furniture item. Referenced by `catalog_items.item_ids`, `items.id`, and many other tables via foreign key.
 | :--- | :--- | :--- |
 | **Status** | Unreleased / Discontinued | **Active Development** 🛠️ |
 | **Public Availability** | Never Released (Internal Prototype) | **Dev Preview (Open Source)** |
 | **Production Ready** | No | ❌ **ABSOLUTELY NOT (Wipe Risk)** |
 | **Catalog Size** | ~31,000 Items (Projected) | **52,000+ Items (Massive Expansion)** 📦 |
 | **Nitro v3 Support**| Partial / Experimental | **100% Full Native Support** |
 | **Stability Level** | Poor / Flawed Queries | **Critical Bugs (High Risk Layout)** |
 | **Query Performance** | Slow Loading Speed | **Blazing Fast Optimized Indexing** |
 | **Layout Integrity** | Missing pages & broken links | **100% Complete Verified Structure** |
 | **Development Cost** | Free (Internal Time) | **100% Free Community Project** ❤️ |
 | **ETA** | — | **No ETA (Under Construction)** |
---
+| 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 |
-## 🐛 Bug Reporting & Current State
+### `catalog_pages`
-Please be aware that this framework currently has an **enormous amount of bugs**. We are committed to tracking down and resolving every single issue, but this process will take a significant amount of time. 
+Defines the hierarchical catalog tree structure visible in the Nitro client.
-**Our Commitment & Rules:**
+| Column | Type | Description |
-* **100% Quality:** We are working hard to ensure that absolutely everything will function **100% flawlessly** in the end. We won't stop until it's perfect.
+|--------|------|-------------|
-* **100% Free:** This entire project is developed completely for free. We are putting in as much effort as we can for the community.
+| `id` | `int(11)` | Primary key |
-* **No ETA & No Nagging:** Because of the massive workload and the fact that we do this for free, it will take a long time. There is no ETA. Please do not nag or complain about progress—be respectful of our time.
+| `parent_id` | `int(11)` | Parent page ID (`-1` = root page) |
-* **Bug Reports:** If you find something broken, you may report it, but keep reports to a minimum for now. Expect many features to be broken or incomplete during this phase.
+| `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`
-## ✨ Planned Nitro v3 Features
+Links items_base entries to catalog_pages with pricing and availability.
-Once the stability phase is complete, this catalog will fully support:
+| Column | Type | Description |
-* **Advanced Catalog Page Layouts:** Native rendering of all specialized Nitro UI tabs and styles.
+|--------|------|-------------|
-* **Dynamic Search & Caching:** Fast indexing to handle the 52k+ items without delaying packet responses.
+| `id` | `int(11)` | Primary key |
-* **Front-end JSON Hooks:** Ready-to-go configurations for your Nitro client assets.
+| `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
-💬 Frequently Asked Questions (FAQ)
+### Emulator (Arcturus Morningstar Extended)
 Q: Can I get a sneak peek or test it on my live hotel?
-A: Absolutely not. As stated above, it contains critical database-wiping bugs. Testing should only be done on an isolated local development environment.
+| 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. |
-Q: Can I help with development or fixing bugs?
+The emulator directly queries all three tables via its DAO layer. No translation or mapping layer is needed.
-A: If you are an experienced developer who understands Nitro v3 packet structures and advanced SQL indexing, feel free to submit a Merge Request.
+### Nitro-V3 (React Client)
-Q: When will it be finished?
+| 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. |
-A: There is no ETA. We work on this for free in our spare time. It will be finished when it's perfect.
+The client does not require any direct database access. All catalog data is served real-time via the emulator's Nitro WebSocket protocol.
-🤝 Contributing
+### Nitro_Render_V3 (Renderer)
 We welcome contributions from the community, provided they meet our standards:
-Fork the repository.
+| 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. |
-Create a clean branch for your bugfix (bugfix/resolve-wipe-issue).
+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.
-Test your SQL queries thoroughly on MySQL 8.0+ / MariaDB 10.5+.
+## Schema Differences
-Open a Merge Request with a detailed explanation of what your code fixes.
+The AtomCMS schema has two extra columns on `catalog_items` compared to the emulator's reference schema:
-🛠️ Development Roadmap
+| Column | AtomCMS | Emulator | Impact |
-[x] Analyze v1 bottlenecks and establish superior base framework.
+|--------|---------|----------|--------|
 | `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`) |
-[x] Merge v1 catalog data into the new clean database structure.
+These are safe additions. The emulator only reads the columns it knows about.
-[/] Expand and index database to 52,000+ items (In Progress).
+## Data Flow
-[ ] Critical Fix: Resolve database-wipe vulnerability.
+```
 ┌──────────────┐     SQL      ┌──────────────┐   Nitro Protocol   ┌──────────┐   Render Cmds   ┌────────────────┐
 │  MySQL/Maria │ ◄──────────► │  Emulator    │ ◄────────────────► │ Nitro-V3 │ ◄──────────────► │ Nitro_Render_V3│
 │  (items_base,│              │  (Arcturus   │   (WebSocket)      │  (React)  │                  │  (PixiJS)      │
 │   catalog_*, │              │   Morningstar│                    │           │                  │                │
 │   ...)       │              │   Extended)  │                    │           │                  │                │
 └──────────────┘              └──────────────┘                    └──────────┘                  └────────────────┘
 ```
-[ ] Systematic bug hunting and framework stability overhaul (Long-term).
+## Reference Data
-[ ] Final QA testing and structural integrity verification.
+The FullDatabase.sql shipped with the emulator contains:
 - ~10,420 `items_base` rows
 - ~769 `catalog_pages` rows
 - ~10,790 `catalog_items` rows
-⚖️ Legal Disclaimer
+This is the complete, production-ready catalog for Arcturus Morningstar Extended, fully compatible with Nitro-V3 and Nitro_Render_V3 out of the box.
-This is an open-source development preview provided "as-is" without any warranty of any kind. By downloading and importing these files, you assume full responsibility for any data loss, database corruption, or system instability. We are not liable for any damages caused by improper implementation or unpatched development bugs.
+
 ## 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