207 lines
5.8 KiB
Markdown
207 lines
5.8 KiB
Markdown
## 🧰 Developer Notes — System Architecture & Implementation
|
||
|
||
This section explains how the **Code of Conquest Battle System** is structured behind the scenes for developers and modders.
|
||
|
||
---
|
||
|
||
### 🧮 1. Formula Layers
|
||
|
||
Combat calculations occur in **three distinct layers**, each responsible for a specific part of the logic:
|
||
|
||
| Layer | Purpose | Example |
|
||
|--------|----------|----------|
|
||
| **Base Layer** | Core attributes and level-based growth. | STR, DEX, INT, etc. |
|
||
| **Derived Layer** | Recalculates combat-ready stats from base values and equipment. | ATK, DEF, ACC, etc. |
|
||
| **Resolution Layer** | Executes battle outcomes using deterministic formulas. | Damage, Crit, AlignmentBonus, etc. |
|
||
|
||
Each layer feeds cleanly into the next.
|
||
This modular approach ensures stats can be recalculated at any time without breaking the combat state.
|
||
|
||
---
|
||
|
||
### ⚙️ 2. Suggested Class Structure
|
||
|
||
The system can be built around **data-driven classes**:
|
||
|
||
```python
|
||
class Character:
|
||
name: str
|
||
level: int
|
||
alignment: int
|
||
attributes: Attributes # STR, DEX, INT, etc.
|
||
equipment: Equipment
|
||
derived_stats: DerivedStats
|
||
|
||
class Attributes:
|
||
str: int
|
||
dex: int
|
||
int: int
|
||
wis: int
|
||
lck: int
|
||
cha: int
|
||
|
||
class DerivedStats:
|
||
atk: int
|
||
mag: int
|
||
def_: int
|
||
mdef: int
|
||
acc: float
|
||
eva: float
|
||
crit: float
|
||
res: float
|
||
````
|
||
|
||
All formulas (like ATK = STR × 2 + WeaponBonus) live inside the `DerivedStats.recalculate()` method.
|
||
Skills and combat outcomes can then safely reference `character.derived_stats`.
|
||
|
||
---
|
||
|
||
### 📜 3. Skill Definitions
|
||
|
||
Skills should be stored as **external data files** (YAML or JSON) for easy modification and expansion.
|
||
|
||
Example:
|
||
|
||
```yaml
|
||
# skills/power_slash.yaml
|
||
id: power_slash
|
||
name: Power Slash
|
||
type: melee
|
||
description: A strong physical strike with reduced accuracy.
|
||
modifiers:
|
||
damage_multiplier: 1.5
|
||
accuracy_multiplier: 0.9
|
||
crit_bonus: 0.0
|
||
conditions:
|
||
requires_weapon_type: sword
|
||
```
|
||
|
||
When combat is resolved, the system loads the skill data dynamically:
|
||
|
||
```python
|
||
damage *= skill.damage_multiplier
|
||
accuracy *= skill.accuracy_multiplier
|
||
```
|
||
|
||
This keeps gameplay logic **data-driven** and **easily expandable**.
|
||
|
||
---
|
||
|
||
### 🧠 4. Combat Resolution Flow
|
||
|
||
A full attack resolves in five modular steps:
|
||
|
||
1. **Precheck Phase** — confirm turn order, skill requirements, status effects.
|
||
2. **Accuracy Phase** — roll for hit using `ACC` vs target `EVA`.
|
||
3. **Damage Phase** — calculate raw damage using formulas.
|
||
4. **Modifier Phase** — apply critical hits, alignment bonus, buffs/debuffs.
|
||
5. **Finalize Phase** — subtract HP, trigger effects, narrate outcome.
|
||
|
||
Each step can be represented by its own method or even subclass (useful for custom battle systems later).
|
||
|
||
---
|
||
|
||
### ⚖️ 5. Alignment & Morality Hooks
|
||
|
||
Alignment is stored as a simple integer between –100 and +100.
|
||
|
||
When calculating damage:
|
||
|
||
```python
|
||
alignment_difference = abs(attacker.alignment - target.alignment)
|
||
alignment_bonus = (alignment_difference / 10) / 100
|
||
damage *= 1 + alignment_bonus
|
||
```
|
||
|
||
Later expansions might include:
|
||
|
||
* **Morality events** that shift alignment based on choices.
|
||
* **Faction modifiers** (e.g., “Paladin vs Undead” adds extra scaling).
|
||
* **Spells** that interact directly with alignment (“Smite Evil,” “Corrupt Heart”).
|
||
|
||
---
|
||
|
||
### 🍀 6. Luck Integration Strategy
|
||
|
||
Luck is treated as a *global adjustment factor* that nudges probability outcomes and variance rolls upward slightly.
|
||
Instead of directly changing RNG, it *biases* existing rolls.
|
||
|
||
```python
|
||
def apply_luck_bias(base_value: float, luck: int) -> float:
|
||
bias = 1 + (luck * 0.002) # +0.2% per point of Luck
|
||
return base_value * bias
|
||
```
|
||
|
||
This keeps outcomes unpredictable yet fair — luckier characters simply lean toward better odds over time.
|
||
|
||
---
|
||
|
||
### 📈 7. Level Scaling Curves
|
||
|
||
Scaling should be **class-specific** and controlled via external tables:
|
||
|
||
```yaml
|
||
# growth_curves/guardian.yaml
|
||
str_growth: high
|
||
dex_growth: low
|
||
int_growth: low
|
||
wis_growth: medium
|
||
lck_growth: low
|
||
cha_growth: medium
|
||
```
|
||
|
||
When leveling up:
|
||
|
||
```python
|
||
new_value = old_value + growth_table.get(attribute).calculate(level)
|
||
```
|
||
|
||
You can easily balance or tweak these tables without touching core logic.
|
||
|
||
---
|
||
|
||
### 🧩 8. Extensibility Hooks
|
||
|
||
Future systems can layer naturally on top of this design:
|
||
|
||
* **Elemental Affinities:** Fire, Ice, Lightning resistances.
|
||
* **Buff & Debuff States:** stored as timed modifiers.
|
||
* **Equipment Enchantments:** simple additive multipliers.
|
||
* **Status Effects:** stored as objects (e.g., `Status("Burning", duration=3, dot=5)`).
|
||
|
||
Each additional system only needs to plug into the Resolution Phase as a pre/post modifier.
|
||
|
||
---
|
||
|
||
### 🧱 9. Design Philosophy for Developers
|
||
|
||
1. **Transparency over randomness** — deterministic math first, variance second.
|
||
2. **Data before code** — YAML or JSON defines skills, growth, and buffs.
|
||
3. **Layered structure** — base → derived → resolution → output.
|
||
4. **Alignment matters** — every moral choice has mechanical consequence.
|
||
5. **Luck is universal** — a soft bias across all rolls, never a chaos driver.
|
||
6. **Readable outputs** — easy for AI or human narrators to describe battle results.
|
||
|
||
---
|
||
|
||
### 🧾 10. Future Expansion Notes
|
||
|
||
* **Elemental Damage Types** (`fire`, `ice`, `holy`, `dark`).
|
||
* **Combo Systems** (chain attacks between party members).
|
||
* **Morale System** (CHA and WIS affecting group performance).
|
||
* **Dynamic Battle Narration** (AI-driven storytelling from combat logs).
|
||
* **Procedural Skill Fusion** (merge abilities to create new ones).
|
||
|
||
---
|
||
|
||
> **Implementation Tip:**
|
||
> Keep every formula centralized in a single `Formulas` or `BattleMath` class.
|
||
> This ensures balancing changes never require refactoring gameplay code.
|
||
|
||
---
|
||
|
||
*Developer Reference Version:* 1.0
|
||
*Author:* Code of Conquest Systems Design Team
|
||
*Document Last Updated:* October 2025
|
||
|