16 KiB
16 KiB
Projectile & Equipment System - Implementation Plan
📌 Overview
This document outlines the implementation of:
- New equipment slots (Quiver, Necklace)
- Projectile firing system (arrows, bolts, javelins)
- Quiver container system (holds multiple ammunition types)
- Arrow recovery mechanics (5% base chance)
- Damage calculation for ranged weapons
- Damage notifications for both players and mobs
🗂️ Phase 1: Database Schema Changes
1.1 Equipment Slots
Status: ✅ COMPLETED
- Added
NecklacetoDungeonEquipmentSlotenum (position 8) - Added
QuivertoDungeonEquipmentSlotenum (position 11)
1.2 Required Database Migration
SQL Migration:
-- Add new enum values (MySQL handles this automatically via EF migrations)
-- No table schema changes needed - enum values are stored as integers
-- Optional: Add equipped columns to DungeonCharacter for caching
ALTER TABLE `dungeon_characters`
ADD COLUMN `EquippedNecklace` BIGINT UNSIGNED NULL,
ADD COLUMN `EquippedQuiver` BIGINT UNSIGNED NULL;
1.3 Item Type Extensions
New Item Types Needed:
public enum ItemType
{
// Existing...
Weapon,
Armor,
Consumable,
Accessory,
// NEW ADDITIONS:
Ammunition, // Arrows, bolts, javelins (stackable, equippable)
QuiverContainer, // Leather quiver, etc. (container item)
Necklace // Or just use Accessory with EquipSlot = Necklace
}
🎯 Phase 2: Ammunition & Quiver System
2.1 Ammunition Items
Properties:
ItemType = AmmunitionStackable = trueMaxStack = 100(or configurable)EquipSlot = Quiver(can be equipped directly)- Stats that affect damage:
BonusDamage(flat bonus)DamageMultiplier(percentage)ArmorPenetrationCritChance
Examples:
- Wooden Arrow (8-12 damage, common)
- Iron Arrow (15-20 damage, uncommon)
- Fire Arrow (10-15 damage + 5 fire DoT)
- Broadhead Arrow (20-30 damage, +10% armor pen)
2.2 Quiver Container System
Two Modes:
- Direct Ammunition Equip: Place a stack of arrows directly in Quiver slot
- Quiver Container Equip: Place a quiver (container) in Quiver slot, which holds multiple ammo types
Quiver Container Properties:
public class QuiverContainer
{
public int Capacity { get; set; } // Number of ammo slots (e.g., 3-5)
public List<AmmoSlot> Slots { get; set; }
// Optional bonuses from the quiver itself
public int BonusArrowRecovery { get; set; } // +5% recovery chance
public float BonusDrawSpeed { get; set; } // -10% draw time
}
public class AmmoSlot
{
public int ItemDefinitionId { get; set; }
public int Quantity { get; set; }
public int MaxQuantity { get; set; } = 100;
}
Database Storage Options:
- Option A: JSON column on equipped quiver item (
AmmoSlotsJson) - Option B: Separate table
dungeon_quiver_ammo_slots- Links to the character item ID of the equipped quiver
- Allows proper querying and constraints
Recommended: Option B
CREATE TABLE `dungeon_quiver_ammo_slots` (
`Id` BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
`QuiverCharacterItemId` BIGINT UNSIGNED NOT NULL,
`SlotIndex` INT NOT NULL,
`ItemDefinitionId` INT NOT NULL,
`Quantity` INT NOT NULL DEFAULT 0,
FOREIGN KEY (`QuiverCharacterItemId`) REFERENCES `dungeon_character_items`(`Id`) ON DELETE CASCADE,
FOREIGN KEY (`ItemDefinitionId`) REFERENCES `dungeon_item_definitions`(`Id`),
UNIQUE KEY `unique_quiver_slot` (`QuiverCharacterItemId`, `SlotIndex`)
);
🏹 Phase 3: Projectile Firing Mechanics
3.1 Weapon Requirements
Ranged Weapons:
- Bows (require arrows/bolts in quiver)
- Crossbows (require bolts in quiver)
- Javelins (throwable, don't require quiver)
- Throwing knives (throwable, don't require quiver)
Item Properties:
public class DungeonItemDefinition
{
// Existing...
// NEW:
public bool RequiresAmmunition { get; set; } // Bows = true, throwing knives = false
public string? AmmunitionType { get; set; } // "arrow", "bolt", null for throwables
public float ProjectileSpeed { get; set; } // Pixels per second
public int Range { get; set; } // Max range in pixels
}
3.2 Firing Logic Flow
Server-Side (DungeonHandler.cs):
// New opcode: FIRE_PROJECTILE
private async Task HandleFireProjectile(IConnection connection, DungeonPlayerSession session, ReadOnlyMemory<byte> payload, CancellationToken ct)
{
var request = Deserialize<FireProjectileRequest>(payload);
// 1. Validate player has ranged weapon equipped
var weapon = GetEquippedItem(session, DungeonEquipmentSlot.MainHand);
if (weapon == null || weapon.ItemDefinition.Type != ItemType.Weapon)
return;
// 2. Get ammunition
Ammunition? ammo = null;
if (weapon.ItemDefinition.RequiresAmmunition)
{
ammo = ConsumeAmmunitionFromQuiver(session);
if (ammo == null)
{
SendError(connection, "No ammunition!");
return;
}
}
// 3. Create projectile
var projectile = new Projectile
{
Id = Guid.NewGuid(),
OwnerId = session.CharacterId,
X = session.PlayerInstance.X,
Y = session.PlayerInstance.Y,
DirectionX = request.DirectionX,
DirectionY = request.DirectionY,
Speed = weapon.ItemDefinition.ProjectileSpeed,
Range = weapon.ItemDefinition.Range,
Damage = CalculateProjectileDamage(session, weapon, ammo),
DamageType = weapon.ItemDefinition.DamageTypeKey,
AmmunitionDefinitionId = ammo?.ItemDefinitionId
};
// 4. Add to dungeon simulation
dungeon.Projectiles.Add(projectile);
// 5. Broadcast to all players in dungeon
BroadcastProjectileSpawned(dungeon, projectile);
}
3.3 Damage Calculation Formula
private int CalculateProjectileDamage(DungeonPlayerSession session, EquippedItem weapon, Ammunition? ammo)
{
var player = session.PlayerInstance;
var weaponDef = weapon.ItemDefinition;
// Base damage from weapon
int baseDamage = Random.Shared.Next(weaponDef.MinDamage, weaponDef.MaxDamage + 1);
// Add ammunition bonus
if (ammo != null)
{
baseDamage += Random.Shared.Next(ammo.MinDamage, ammo.MaxDamage + 1);
}
// Calculate stat contribution
// Formula: (STR * 0.3 + DEX * 0.7) = stat modifier
float statModifier = (player.Strength * 0.3f + player.Dexterity * 0.7f);
// Apply stat scaling (1% per point)
float statBonus = baseDamage * (statModifier / 100f);
int totalDamage = (int)(baseDamage + statBonus);
return totalDamage;
}
Alternative Formulas to Consider:
- STR 50% / DEX 50%:
(STR * 0.5 + DEX * 0.5) * 0.01 * baseDamage - DEX Only:
DEX * 0.015 * baseDamage(pure dex scaling) - Weapon Dependent: Bows use DEX, crossbows use STR+DEX
💥 Phase 4: Projectile Physics & Collision
4.1 Server-Side Projectile Tick
private void UpdateProjectiles(DungeonInstance dungeon, float deltaTime)
{
var toRemove = new List<Projectile>();
foreach (var projectile in dungeon.Projectiles)
{
// Move projectile
projectile.X += projectile.DirectionX * projectile.Speed * deltaTime;
projectile.Y += projectile.DirectionY * projectile.Speed * deltaTime;
projectile.DistanceTraveled += projectile.Speed * deltaTime;
// Check range
if (projectile.DistanceTraveled >= projectile.Range)
{
toRemove.Add(projectile);
continue;
}
// Check mob collision
foreach (var mob in dungeon.Simulation.Mobs.Values)
{
if (IsColliding(projectile, mob))
{
// Deal damage
ApplyDamage(mob, projectile.Damage, projectile.DamageType);
// Show damage notification
BroadcastDamageNotification(dungeon, mob.Id, projectile.Damage, projectile.DamageType, isCrit: false);
// Arrow recovery chance
if (projectile.AmmunitionDefinitionId.HasValue)
{
TryRecoverArrow(dungeon, projectile, mob);
}
toRemove.Add(projectile);
BroadcastProjectileHit(dungeon, projectile.Id, mob.Id);
break;
}
}
}
// Remove finished projectiles
foreach (var p in toRemove)
dungeon.Projectiles.Remove(p);
}
4.2 Arrow Recovery System
private void TryRecoverArrow(DungeonInstance dungeon, Projectile projectile, MobInstance mob)
{
const float BASE_RECOVERY_CHANCE = 0.05f; // 5%
// TODO: Add bonuses from:
// - Quiver bonuses
// - Skill perks
// - Enchantments
float recoveryChance = BASE_RECOVERY_CHANCE;
if (Random.Shared.NextDouble() < recoveryChance)
{
// Add to mob's guaranteed loot
if (!mob.GuaranteedLoot.ContainsKey(projectile.AmmunitionDefinitionId.Value))
{
mob.GuaranteedLoot[projectile.AmmunitionDefinitionId.Value] = 0;
}
mob.GuaranteedLoot[projectile.AmmunitionDefinitionId.Value]++;
_log.LogDebug("Arrow recovered! Added {AmmoId} to mob {MobId} loot",
projectile.AmmunitionDefinitionId.Value, mob.Id);
}
}
🔔 Phase 5: Damage Notifications
5.1 Server Broadcast
private void BroadcastDamageNotification(
DungeonInstance dungeon,
ulong targetId,
int damage,
string damageType,
bool isCrit,
bool isPlayer = false)
{
var notification = new
{
targetId,
targetType = isPlayer ? "player" : "mob",
damage,
damageType,
isCrit,
timestamp = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()
};
BroadcastToAll(dungeon, DungeonOpCodes.DAMAGE_NOTIFICATION, notification);
}
5.2 Client-Side Display (Pseudocode for Client)
// Client receives DAMAGE_NOTIFICATION
onDamageNotification(data) {
const target = data.targetType === 'player'
? getPlayer(data.targetId)
: getMob(data.targetId);
if (!target) return;
// Create floating damage text
const damageText = {
x: target.x,
y: target.y - 30,
text: `-${data.damage}`,
color: getDamageColor(data.damageType),
fontSize: data.isCrit ? 24 : 16,
duration: 1500,
velocity: { x: 0, y: -50 }
};
floatingTexts.push(damageText);
}
function getDamageColor(damageType) {
switch(damageType) {
case 'physical': return '#ffffff';
case 'fire': return '#ff4500';
case 'ice': return '#00bfff';
case 'poison': return '#00ff00';
case 'holy': return '#ffd700';
default: return '#ffffff';
}
}
🎨 Phase 6: Client-Side Integration Needs
6.1 Required Client Features
-
Input Handling:
- Detect mouse click / attack button
- Calculate direction from player to mouse cursor
- Send
FIRE_PROJECTILEpacket with direction
-
Projectile Rendering:
- Spawn projectile sprite at player position
- Animate movement from server updates
- Play arrow whoosh sound
- Remove on hit/expire
-
UI Updates:
- Quiver slot in equipment panel
- Necklace slot in equipment panel
- Ammunition count display
- Quiver container UI (if using container)
-
Damage Numbers:
- Floating text system
- Color-coded by damage type
- Critical hit animations (larger, different color)
6.2 Network Protocol
New OpCodes:
public enum DungeonOpCodes
{
// Existing...
// NEW:
FIRE_PROJECTILE = 400, // Client → Server
PROJECTILE_SPAWNED = 401, // Server → Client
PROJECTILE_HIT = 402, // Server → Client
PROJECTILE_EXPIRED = 403, // Server → Client
DAMAGE_NOTIFICATION = 404, // Server → Client
QUIVER_UPDATE = 405, // Server → Client (ammo count changed)
}
Packet Structures:
// Client sends this
public class FireProjectileRequest
{
public float DirectionX { get; set; } // Normalized
public float DirectionY { get; set; } // Normalized
}
// Server broadcasts this
public class ProjectileSpawnedEvent
{
public Guid ProjectileId { get; set; }
public ulong OwnerId { get; set; }
public float X { get; set; }
public float Y { get; set; }
public float DirectionX { get; set; }
public float DirectionY { get; set; }
public float Speed { get; set; }
public int SpriteId { get; set; }
}
public class ProjectileHitEvent
{
public Guid ProjectileId { get; set; }
public ulong TargetId { get; set; }
public bool IsPlayer { get; set; }
}
📋 Phase 7: Implementation Checklist
Database & Schema
- Create EF Core migration for new equipment slots
- Add
ItemType.AmmunitionandItemType.QuiverContainer - Create
dungeon_quiver_ammo_slotstable - Add weapon properties:
RequiresAmmunition,AmmunitionType,ProjectileSpeed,Range - Add ammunition properties: damage ranges, bonuses, recovery modifiers
Server-Side Core
- Add
Projectileclass to dungeon simulation - Implement
HandleFireProjectilehandler - Implement
UpdateProjectilestick logic - Implement
CalculateProjectileDamageformula - Implement arrow recovery mechanic
- Add quiver slot handling to equip/unequip logic
- Add necklace slot handling to equip/unequip logic
Quiver Container System
- Create
QuiverContainerentity/model - Implement quiver ammo slot management
- Handle equipping/unequipping quiver containers
- Handle adding/removing ammo from quiver slots
- UI for managing quiver contents (admin panel)
Damage System
- Implement
BroadcastDamageNotification - Add damage type tracking
- Add critical hit logic
- Integrate with existing damage calculation
UI Updates
- Update admin Character.cshtml equipment list (add Quiver, Necklace)
- Update Character.cshtml.cs computed stats (if quiver/necklace provide stats)
- Add quiver management UI (if using containers)
Client-Side (Path Needed!)
- Add FIRE_PROJECTILE input handling
- Add projectile rendering system
- Add damage notification floating text
- Add equipment slots UI (quiver, necklace)
- Add quiver ammo count display
- Add sounds (arrow whoosh, hit, etc.)
Testing
- Test direct ammo equip (stack of arrows in quiver slot)
- Test quiver container equip (quiver with multiple ammo types)
- Test firing with different weapons (bow, crossbow, throwables)
- Test arrow recovery at 5% rate
- Test damage calculations with various stat combinations
- Test damage notifications appearance
- Test edge cases (no ammo, out of range, invalid targets)
🔧 Technical Considerations
Performance
- Projectiles: Limit max projectiles per dungeon (e.g., 100)
- Collision: Use spatial partitioning for large dungeons
- Broadcasting: Only send projectile updates to players in same dungeon
Balance
- Arrow Recovery: Start at 5%, allow buffs up to 100%
- Damage Scaling: Fine-tune STR/DEX ratio after testing
- Ammunition Cost: Make arrows cheap enough to use freely
- Quiver Capacity: 3-5 slots for containers, 100 stack for direct equip
Security
- Validate Direction: Ensure normalized vectors
- Rate Limiting: Prevent spam (max 2-3 attacks per second)
- Range Checks: Don't trust client, validate server-side
- Ammunition Checks: Server is source of truth for ammo count
🚀 Recommended Implementation Order
- ✅ Phase 1: Database schema (equipment slots enum) - DONE
- Phase 2: Database migration + ammunition item types
- Phase 3: Basic projectile firing (no quiver, simple damage)
- Phase 4: Damage notifications
- Phase 5: Arrow recovery mechanic
- Phase 6: Quiver container system
- Phase 7: Client-side rendering & UI
- Phase 8: Polish, balancing, testing
❓ Questions for You
- Client Path: What's the absolute path to your client codebase?
- Client Technology: What's the client built with? (Unity, Godot, Phaser, custom engine?)
- Quiver Preference: Should we start with simple (direct ammo equip) or complex (container system)?
- Damage Formula: Prefer STR 30% / DEX 70%, or different ratio?
- Arrow Recovery: Should recovery chance vary by arrow type? (cheap arrows = 5%, expensive = 20%)
- Throwables: Should throwing knives/axes consume from inventory or be infinite?
Let me know your answers and I'll proceed with implementation!