diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md new file mode 100644 index 0000000..418a3bc --- /dev/null +++ b/docs/CONFIGURATION.md @@ -0,0 +1,160 @@ +# Configuration Guide + +This document outlines the structure and available options for the `config/config.json` file. The configuration is validated using Zod schemas at runtime (see `src/lib/config.ts`). + +## Core Structure + +### Leveling +Configuration for the XP and leveling system. + +| Field | Type | Description | +|-------|------|-------------| +| `base` | `number` | The base XP required for the first level. | +| `exponent` | `number` | The exponent used to calculate XP curves. | +| `chat.cooldownMs` | `number` | Time in milliseconds between XP gains from chat. | +| `chat.minXp` | `number` | Minimum XP awarded per message. | +| `chat.maxXp` | `number` | Maximum XP awarded per message. | + +### Economy +Settings for currency, rewards, and transfers. + +#### Daily +| Field | Type | Description | +|-------|------|-------------| +| `amount` | `integer` | Base amount granted by `/daily`. | +| `streakBonus` | `integer` | Bonus amount per streak day. | +| `weeklyBonus` | `integer` | Bonus amount for a 7-day streak. | +| `cooldownMs` | `number` | Cooldown period for the command (usually 24h). | + +#### Transfers +| Field | Type | Description | +|-------|------|-------------| +| `allowSelfTransfer` | `boolean` | Whether users can transfer money to themselves. | +| `minAmount` | `integer` | Minimum amount required for a transfer. | + +#### Exam +| Field | Type | Description | +|-------|------|-------------| +| `multMin` | `number` | Minimum multiplier for exam rewards. | +| `multMax` | `number` | Maximum multiplier for exam rewards. | + +### Inventory +| Field | Type | Description | +|-------|------|-------------| +| `maxStackSize` | `integer` | Maximum count of a single item in one slot. | +| `maxSlots` | `number` | Total number of inventory slots available. | + +### Lootdrop +Settings for the random chat loot drop events. + +| Field | Type | Description | +|-------|------|-------------| +| `activityWindowMs` | `number` | Time window to track activity for spawning drops. | +| `minMessages` | `number` | Minimum messages required in window to trigger drop. | +| `spawnChance` | `number` | Probability (0-1) of a drop spawning when conditions met. | +| `cooldownMs` | `number` | Minimum time between loot drops. | +| `reward.min` | `number` | Minimum currency reward. | +| `reward.max` | `number` | Maximum currency reward. | +| `reward.currency` | `string` | The currency ID/Symbol used for rewards. | + +### Roles +| Field | Type | Description | +|-------|------|-------------| +| `studentRole` | `string` | Discord Role ID for students. | +| `visitorRole` | `string` | Discord Role ID for visitors. | +| `colorRoles` | `string[]` | List of Discord Role IDs available as color roles. | + +### Moderation +Automated moderation settings. + +#### Prune +| Field | Type | Description | +|-------|------|-------------| +| `maxAmount` | `number` | Maximum messages to delete in one go. | +| `confirmThreshold` | `number` | Amount above which confirmation is required. | +| `batchSize` | `number` | Size of delete batches. | +| `batchDelayMs` | `number` | Delay between batches. | + +#### Cases +| Field | Type | Description | +|-------|------|-------------| +| `dmOnWarn` | `boolean` | Whether to DM users when they are warned. | +| `logChannelId` | `string` | (Optional) Channel ID for moderation logs. | +| `autoTimeoutThreshold` | `number` | (Optional) Warn count to trigger auto-timeout. | + +### System & Misc +| Field | Type | Description | +|-------|------|-------------| +| `commands` | `Object` | Map of command names (keys) to boolean (values) to enable/disable them. | +| `welcomeChannelId` | `string` | (Optional) Channel ID for welcome messages. | +| `welcomeMessage` | `string` | (Optional) Custom welcome message text. | +| `feedbackChannelId` | `string` | (Optional) Channel ID where feedback is posted. | +| `terminal.channelId` | `string` | (Optional) Channel ID for terminal display. | +| `terminal.messageId` | `string` | (Optional) Message ID for terminal display. | + +## Example Config + +```json +{ + "leveling": { + "base": 100, + "exponent": 1.5, + "chat": { + "cooldownMs": 60000, + "minXp": 15, + "maxXp": 25 + } + }, + "economy": { + "daily": { + "amount": "100", + "streakBonus": "10", + "weeklyBonus": "500", + "cooldownMs": 86400000 + }, + "transfers": { + "allowSelfTransfer": false, + "minAmount": "10" + }, + "exam": { + "multMin": 1.0, + "multMax": 2.0 + } + }, + "inventory": { + "maxStackSize": "99", + "maxSlots": 20 + }, + "lootdrop": { + "activityWindowMs": 300000, + "minMessages": 10, + "spawnChance": 0.05, + "cooldownMs": 3600000, + "reward": { + "min": 50, + "max": 150, + "currency": "CREDITS" + } + }, + "commands": { + "example": true + }, + "studentRole": "123456789012345678", + "visitorRole": "123456789012345678", + "colorRoles": [], + "moderation": { + "prune": { + "maxAmount": 100, + "confirmThreshold": 50, + "batchSize": 100, + "batchDelayMs": 1000 + }, + "cases": { + "dmOnWarn": true + } + } +} +``` + +> [!NOTE] +> Fields marked as `integer` or `bigint` in the types can often be provided as strings in the JSON to ensure precision, but the system handles parsing them. diff --git a/docs/LOOTBOX_GUIDE.md b/docs/LOOTBOX_GUIDE.md new file mode 100644 index 0000000..fd986c4 --- /dev/null +++ b/docs/LOOTBOX_GUIDE.md @@ -0,0 +1,127 @@ +# Lootbox Creation Guide + +Currently, the Item Wizard does not support creating **Lootbox** items directly. Instead, they must be inserted manually into the database. This guide details the required JSON structure for the `LOOTBOX` effect. + +## Item Structure + +To create a lootbox, you need to insert a row into the `items` table. The critical part is the `usageData` JSON column. + +```json +{ + "consume": true, + "effects": [ + { + "type": "LOOTBOX", + "pool": [ ... ] + } + ] +} +``` + +## Loot Table Structure + +The `pool` property is an array of `LootTableItem` objects. A random item is selected based on the total `weight` of all items in the pool. + +| Field | Type | Description | +|-------|------|-------------| +| `type` | `string` | One of: `CURRENCY`, `ITEM`, `XP`, `NOTHING`. | +| `weight` | `number` | The relative probability weight of this outcome. | +| `message` | `string` | (Optional) Custom message to display when this outcome is selected. | + +### Outcome Types + +#### 1. Currency +Gives the user coins. + +```json +{ + "type": "CURRENCY", + "weight": 50, + "amount": 100, // Fixed amount OR + "minAmount": 50, // Minimum random amount + "maxAmount": 150 // Maximum random amount +} +``` + +#### 2. XP +Gives the user Experience Points. + +```json +{ + "type": "XP", + "weight": 30, + "amount": 500 // Fixed amount OR range (minAmount/maxAmount) +} +``` + +#### 3. Item +Gives the user another item (by ID). + +```json +{ + "type": "ITEM", + "weight": 10, + "itemId": 42, // The ID of the item to give + "amount": 1 // (Optional) Quantity to give, default 1 +} +``` + +#### 4. Nothing +An empty roll. + +```json +{ + "type": "NOTHING", + "weight": 10, + "message": "The box was empty! Better luck next time." +} +``` + +## Complete Example + +Here is a full SQL insert example (using a hypothetical SQL client or Drizzle studio) for a "Basic Lootbox": + +**Name**: Basic Lootbox +**Type**: CONSUMABLE +**Effect**: +- 50% chance for 100-200 Coins +- 30% chance for 500 XP +- 10% chance for Item ID 5 (e.g. Rare Gem) +- 10% chance for Nothing + +**JSON for `usageData`**: +```json +{ + "consume": true, + "effects": [ + { + "type": "LOOTBOX", + "pool": [ + { + "type": "CURRENCY", + "weight": 50, + "minAmount": 100, + "maxAmount": 200 + }, + { + "type": "XP", + "weight": 30, + "amount": 500 + }, + { + "type": "ITEM", + "weight": 10, + "itemId": 5, + "amount": 1, + "message": "Startstruck! You found a Rare Gem!" + }, + { + "type": "NOTHING", + "weight": 10, + "message": "It's empty..." + } + ] + } + ] +} +```