novo
This commit is contained in:
@@ -0,0 +1,591 @@
|
||||
# 🔧 ANTIGRAVITY NAMESPACE REFACTOR
|
||||
**Unifying All Systems Under Single Namespace**
|
||||
|
||||
**Date:** 10.12.2025
|
||||
**Status:** 📋 PLANNED (Future)
|
||||
**Priority:** 🟢 LOW (Post-1.0)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 **Goal:**
|
||||
|
||||
Poenotiti vse sisteme v enoten `Antigravity` namespace za:
|
||||
- Better code organization
|
||||
- Avoid global namespace pollution
|
||||
- Easier debugging
|
||||
- Clearer dependencies
|
||||
- Professional code structure
|
||||
|
||||
---
|
||||
|
||||
## 📊 **Current State Analysis:**
|
||||
|
||||
### **Problem:**
|
||||
Currently systems are scattered:
|
||||
```javascript
|
||||
// Global classes
|
||||
class Player { }
|
||||
class TerrainSystem { }
|
||||
class FarmingSystem { }
|
||||
class WeatherSystem { }
|
||||
// ... 30+ more classes
|
||||
|
||||
// Global variables
|
||||
let gameScene;
|
||||
let uiScene;
|
||||
let player;
|
||||
|
||||
// Mix of patterns
|
||||
```
|
||||
|
||||
**Issues:**
|
||||
- ❌ Global namespace pollution (40+ global classes)
|
||||
- ❌ No clear structure
|
||||
- ❌ Hard to track dependencies
|
||||
- ❌ Potential naming conflicts
|
||||
- ❌ Difficult to refactor
|
||||
|
||||
---
|
||||
|
||||
## ✅ **Proposed Structure:**
|
||||
|
||||
### **Antigravity Namespace:**
|
||||
|
||||
```javascript
|
||||
const Antigravity = {
|
||||
// Core Engine
|
||||
Core: {
|
||||
Engine: { ... },
|
||||
GameLoop: { ... },
|
||||
EventBus: { ... },
|
||||
StateManager: { ... }
|
||||
},
|
||||
|
||||
// Systems
|
||||
Systems: {
|
||||
Terrain: TerrainSystem,
|
||||
Farming: FarmingSystem,
|
||||
Weather: WeatherSystem,
|
||||
Inventory: InventorySystem,
|
||||
Combat: CombatSystem,
|
||||
Building: BuildingSystem,
|
||||
Quest: QuestSystem,
|
||||
Save: SaveSystem,
|
||||
Sound: SoundManager,
|
||||
Particle: ParticleEffects,
|
||||
// ... all 33 systems
|
||||
},
|
||||
|
||||
// Entities
|
||||
Entities: {
|
||||
Player: Player,
|
||||
NPC: NPC,
|
||||
Zombie: Zombie,
|
||||
Boss: Boss,
|
||||
LootChest: LootChest,
|
||||
ZombieSpawner: ZombieSpawner
|
||||
},
|
||||
|
||||
// Utilities
|
||||
Utils: {
|
||||
Isometric: IsometricUtils,
|
||||
PerlinNoise: PerlinNoise,
|
||||
Pathfinding: Pathfinding,
|
||||
SpatialGrid: SpatialGrid,
|
||||
ObjectPool: ObjectPool,
|
||||
Compression: Compression
|
||||
},
|
||||
|
||||
// Data
|
||||
Data: {
|
||||
Items: ITEMS_DATA,
|
||||
Recipes: CRAFTING_RECIPES,
|
||||
NPCs: NPC_DATA,
|
||||
Quests: QUEST_DATA,
|
||||
Localization: TRANSLATIONS
|
||||
},
|
||||
|
||||
// Constants
|
||||
Constants: {
|
||||
TILE_SIZE: 48,
|
||||
GRID_WIDTH: 100,
|
||||
GRID_HEIGHT: 100,
|
||||
PLAYER_SPEED: 200,
|
||||
// ... all constants
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 **Migration Strategy:**
|
||||
|
||||
### **Phase 1: Create Namespace Structure**
|
||||
|
||||
**Step 1.1: Create Antigravity.js Core**
|
||||
```javascript
|
||||
// src/core/Antigravity.js
|
||||
window.Antigravity = {
|
||||
version: '1.0.0',
|
||||
Core: {},
|
||||
Systems: {},
|
||||
Entities: {},
|
||||
Utils: {},
|
||||
Data: {},
|
||||
Constants: {}
|
||||
};
|
||||
|
||||
// Helper methods
|
||||
Antigravity.registerSystem = function(name, system) {
|
||||
this.Systems[name] = system;
|
||||
console.log(`✅ Registered system: ${name}`);
|
||||
};
|
||||
|
||||
Antigravity.getSystem = function(name) {
|
||||
return this.Systems[name];
|
||||
};
|
||||
```
|
||||
|
||||
**Time:** 2 hours
|
||||
|
||||
---
|
||||
|
||||
### **Phase 2: Migrate Systems (33 files)**
|
||||
|
||||
**Example Migration:**
|
||||
|
||||
**Before:**
|
||||
```javascript
|
||||
// TerrainSystem.js
|
||||
class TerrainSystem {
|
||||
constructor(scene) {
|
||||
this.scene = scene;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**After:**
|
||||
```javascript
|
||||
// TerrainSystem.js
|
||||
(function(Antigravity) {
|
||||
'use strict';
|
||||
|
||||
class TerrainSystem {
|
||||
constructor(scene) {
|
||||
this.scene = scene;
|
||||
}
|
||||
}
|
||||
|
||||
// Register to namespace
|
||||
Antigravity.Systems.Terrain = TerrainSystem;
|
||||
|
||||
})(window.Antigravity);
|
||||
```
|
||||
|
||||
**Priority Order:**
|
||||
1. Core systems (5 files) - 1 day
|
||||
2. Game systems (15 files) - 2 days
|
||||
3. Utility systems (8 files) - 1 day
|
||||
4. Optional systems (5 files) - 1 day
|
||||
|
||||
**Total Time:** 5 days
|
||||
|
||||
---
|
||||
|
||||
### **Phase 3: Update Usage**
|
||||
|
||||
**Before:**
|
||||
```javascript
|
||||
// GameScene.js
|
||||
this.terrainSystem = new TerrainSystem(this);
|
||||
this.farmingSystem = new FarmingSystem(this);
|
||||
```
|
||||
|
||||
**After:**
|
||||
```javascript
|
||||
// GameScene.js
|
||||
this.terrainSystem = new Antigravity.Systems.Terrain(this);
|
||||
this.farmingSystem = new Antigravity.Systems.Farming(this);
|
||||
|
||||
// Or with helper:
|
||||
this.terrainSystem = Antigravity.createSystem('Terrain', this);
|
||||
```
|
||||
|
||||
**Files to Update:**
|
||||
- GameScene.js
|
||||
- UIScene.js
|
||||
- StoryScene.js
|
||||
- Player.js
|
||||
- All entity files
|
||||
|
||||
**Time:** 2 days
|
||||
|
||||
---
|
||||
|
||||
### **Phase 4: Migrate Constants**
|
||||
|
||||
**Before:**
|
||||
```javascript
|
||||
// Scattered across files
|
||||
const TILE_SIZE = 48;
|
||||
const GRID_WIDTH = 100;
|
||||
```
|
||||
|
||||
**After:**
|
||||
```javascript
|
||||
// constants.js
|
||||
Antigravity.Constants = {
|
||||
World: {
|
||||
TILE_SIZE: 48,
|
||||
GRID_WIDTH: 100,
|
||||
GRID_HEIGHT: 100
|
||||
},
|
||||
Player: {
|
||||
SPEED: 200,
|
||||
MAX_HEALTH: 100,
|
||||
MAX_ENERGY: 100
|
||||
},
|
||||
Game: {
|
||||
FPS_TARGET: 60,
|
||||
SAVE_INTERVAL: 300000 // 5 min
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
**Time:** 1 day
|
||||
|
||||
---
|
||||
|
||||
### **Phase 5: Create Data Registry**
|
||||
|
||||
```javascript
|
||||
Antigravity.Data = {
|
||||
Items: {
|
||||
get(id) {
|
||||
return ITEMS_DATA[id];
|
||||
},
|
||||
getAll() {
|
||||
return ITEMS_DATA;
|
||||
}
|
||||
},
|
||||
Recipes: {
|
||||
get(id) {
|
||||
return CRAFTING_RECIPES.find(r => r.id === id);
|
||||
},
|
||||
getCraftable(inventory) {
|
||||
// Logic to check craftable recipes
|
||||
}
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
**Time:** 2 days
|
||||
|
||||
---
|
||||
|
||||
## 📁 **File Structure After Refactor:**
|
||||
|
||||
```
|
||||
src/
|
||||
├── core/
|
||||
│ ├── Antigravity.js # Main namespace
|
||||
│ ├── Engine.js # Core engine
|
||||
│ ├── EventBus.js # Event system
|
||||
│ └── StateManager.js # State management
|
||||
│
|
||||
├── systems/
|
||||
│ ├── TerrainSystem.js # Antigravity.Systems.Terrain
|
||||
│ ├── FarmingSystem.js # Antigravity.Systems.Farming
|
||||
│ └── ... # All systems
|
||||
│
|
||||
├── entities/
|
||||
│ ├── Player.js # Antigravity.Entities.Player
|
||||
│ ├── NPC.js # Antigravity.Entities.NPC
|
||||
│ └── ...
|
||||
│
|
||||
├── utils/
|
||||
│ ├── IsometricUtils.js # Antigravity.Utils.Isometric
|
||||
│ └── ...
|
||||
│
|
||||
├── data/
|
||||
│ ├── items.js # Antigravity.Data.Items
|
||||
│ ├── recipes.js # Antigravity.Data.Recipes
|
||||
│ └── constants.js # Antigravity.Constants
|
||||
│
|
||||
└── scenes/
|
||||
├── GameScene.js
|
||||
├── UIScene.js
|
||||
└── ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ **Benefits:**
|
||||
|
||||
### **Code Organization:**
|
||||
- ✅ Clear structure (Systems, Entities, Utils, Data)
|
||||
- ✅ Easy to find files
|
||||
- ✅ Logical grouping
|
||||
- ✅ Better IDE autocomplete
|
||||
|
||||
### **Namespace Management:**
|
||||
- ✅ Only 1 global variable (`Antigravity`)
|
||||
- ✅ No naming conflicts
|
||||
- ✅ Clear dependencies
|
||||
- ✅ Easy to debug
|
||||
|
||||
### **Developer Experience:**
|
||||
- ✅ Consistent API
|
||||
- ✅ Better documentation
|
||||
- ✅ Easier onboarding
|
||||
- ✅ Professional structure
|
||||
|
||||
### **Performance:**
|
||||
- ✅ No global lookup overhead
|
||||
- ✅ Easier to optimize
|
||||
- ✅ Better minification
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ **Risks & Mitigation:**
|
||||
|
||||
### **Risk 1: Breaking Changes**
|
||||
**Impact:** HIGH
|
||||
**Mitigation:**
|
||||
- Create compatibility layer
|
||||
- Gradual migration (system by system)
|
||||
- Extensive testing
|
||||
- Keep backup branch
|
||||
|
||||
### **Risk 2: Time Investment**
|
||||
**Impact:** MEDIUM
|
||||
**Mitigation:**
|
||||
- Do AFTER 1.0 release
|
||||
- Spread over 2-3 weeks
|
||||
- Low priority task
|
||||
|
||||
### **Risk 3: Learning Curve**
|
||||
**Impact:** LOW
|
||||
**Mitigation:**
|
||||
- Clear documentation
|
||||
- Migration examples
|
||||
- Gradual rollout
|
||||
|
||||
---
|
||||
|
||||
## 📅 **Timeline:**
|
||||
|
||||
### **Phase 1: Planning & Setup** (1 week)
|
||||
- [ ] Create Antigravity.js core
|
||||
- [ ] Design namespace structure
|
||||
- [ ] Create migration guide
|
||||
- [ ] Setup compatibility layer
|
||||
|
||||
### **Phase 2: Core Migration** (1 week)
|
||||
- [ ] Migrate 10 core systems
|
||||
- [ ] Update GameScene
|
||||
- [ ] Test core functionality
|
||||
- [ ] Fix critical issues
|
||||
|
||||
### **Phase 3: Full Migration** (1 week)
|
||||
- [ ] Migrate remaining 23 systems
|
||||
- [ ] Migrate all entities
|
||||
- [ ] Migrate all utilities
|
||||
- [ ] Update all scenes
|
||||
|
||||
### **Phase 4: Data & Constants** (3 days)
|
||||
- [ ] Consolidate constants
|
||||
- [ ] Create data registry
|
||||
- [ ] Update references
|
||||
- [ ] Documentation
|
||||
|
||||
### **Phase 5: Testing & Polish** (3 days)
|
||||
- [ ] Comprehensive testing
|
||||
- [ ] Performance benchmarks
|
||||
- [ ] Bug fixes
|
||||
- [ ] Final documentation
|
||||
|
||||
**Total Time:** ~3-4 weeks
|
||||
|
||||
---
|
||||
|
||||
## 🔧 **Implementation Examples:**
|
||||
|
||||
### **System Registration:**
|
||||
|
||||
```javascript
|
||||
// OLD WAY:
|
||||
class FarmingSystem {
|
||||
// ...
|
||||
}
|
||||
|
||||
// NEW WAY:
|
||||
(function(AG) {
|
||||
class FarmingSystem {
|
||||
// ...
|
||||
}
|
||||
|
||||
AG.registerSystem('Farming', FarmingSystem);
|
||||
})(Antigravity);
|
||||
```
|
||||
|
||||
### **System Usage:**
|
||||
|
||||
```javascript
|
||||
// OLD WAY:
|
||||
this.farmingSystem = new FarmingSystem(this);
|
||||
this.farmingSystem.plantCrop(x, y, 'wheat');
|
||||
|
||||
// NEW WAY:
|
||||
this.farming = new Antigravity.Systems.Farming(this);
|
||||
this.farming.plantCrop(x, y, 'wheat');
|
||||
|
||||
// OR with factory:
|
||||
this.farming = Antigravity.createSystem('Farming', this);
|
||||
```
|
||||
|
||||
### **Accessing Data:**
|
||||
|
||||
```javascript
|
||||
// OLD WAY:
|
||||
const item = ITEMS_DATA['wheat'];
|
||||
const recipe = CRAFTING_RECIPES.find(r => r.id === 'bread');
|
||||
|
||||
// NEW WAY:
|
||||
const item = Antigravity.Data.Items.get('wheat');
|
||||
const recipe = Antigravity.Data.Recipes.get('bread');
|
||||
```
|
||||
|
||||
### **Using Constants:**
|
||||
|
||||
```javascript
|
||||
// OLD WAY:
|
||||
const speed = PLAYER_SPEED;
|
||||
const size = TILE_SIZE;
|
||||
|
||||
// NEW WAY:
|
||||
const speed = Antigravity.Constants.Player.SPEED;
|
||||
const size = Antigravity.Constants.World.TILE_SIZE;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 **Migration Checklist:**
|
||||
|
||||
### **Core (Priority 1):**
|
||||
- [ ] Antigravity.js namespace
|
||||
- [ ] TerrainSystem
|
||||
- [ ] Player
|
||||
- [ ] InventorySystem
|
||||
- [ ] WeatherSystem
|
||||
|
||||
### **Game Systems (Priority 2):**
|
||||
- [ ] FarmingSystem
|
||||
- [ ] BuildingSystem
|
||||
- [ ] CombatSystem
|
||||
- [ ] QuestSystem
|
||||
- [ ] SaveSystem
|
||||
- [ ] SoundManager
|
||||
- [ ] ParticleEffects
|
||||
- [ ] (+ 8 more)
|
||||
|
||||
### **Entities (Priority 3):**
|
||||
- [ ] NPC
|
||||
- [ ] Zombie
|
||||
- [ ] Boss
|
||||
- [ ] LootChest
|
||||
- [ ] ZombieSpawner
|
||||
|
||||
### **Utilities (Priority 4):**
|
||||
- [ ] IsometricUtils
|
||||
- [ ] PerlinNoise
|
||||
- [ ] Pathfinding
|
||||
- [ ] SpatialGrid
|
||||
- [ ] ObjectPool
|
||||
|
||||
### **Data & Constants (Priority 5):**
|
||||
- [ ] Constants consolidation
|
||||
- [ ] Items data
|
||||
- [ ] Recipes data
|
||||
- [ ] Localizations
|
||||
- [ ] Quest data
|
||||
|
||||
---
|
||||
|
||||
## 💡 **Compatibility Layer:**
|
||||
|
||||
```javascript
|
||||
// antigravity-compat.js
|
||||
// Provides backwards compatibility during migration
|
||||
|
||||
// Redirect old global classes to new namespace
|
||||
window.TerrainSystem = Antigravity.Systems.Terrain;
|
||||
window.FarmingSystem = Antigravity.Systems.Farming;
|
||||
window.Player = Antigravity.Entities.Player;
|
||||
|
||||
console.warn('⚠️ Using compatibility layer. Please migrate to Antigravity namespace.');
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 **Success Metrics:**
|
||||
|
||||
### **Code Quality:**
|
||||
- ✅ Only 1 global variable
|
||||
- ✅ Clear file structure
|
||||
- ✅ Consistent API
|
||||
- ✅ No naming conflicts
|
||||
|
||||
### **Developer Experience:**
|
||||
- ✅ Faster development
|
||||
- ✅ Better autocomplete
|
||||
- ✅ Easier debugging
|
||||
- ✅ Clear documentation
|
||||
|
||||
### **Performance:**
|
||||
- ✅ No regression
|
||||
- ✅ Better minification
|
||||
- ✅ Faster lookup times
|
||||
|
||||
---
|
||||
|
||||
## 📝 **Documentation Needed:**
|
||||
|
||||
1. **Migration Guide** - Step-by-step for developers
|
||||
2. **API Reference** - Complete namespace documentation
|
||||
3. **Examples** - Before/after comparisons
|
||||
4. **Troubleshooting** - Common migration issues
|
||||
|
||||
---
|
||||
|
||||
## 🚀 **When to Do This:**
|
||||
|
||||
### **NOT NOW because:**
|
||||
- ⏳ Still in active development
|
||||
- ⏳ Beta release coming soon
|
||||
- ⏳ Risk of breaking changes
|
||||
- ⏳ Time better spent on features
|
||||
|
||||
### **DO AFTER:**
|
||||
- ✅ 1.0 Release complete
|
||||
- ✅ Game is stable
|
||||
- ✅ Core features done
|
||||
- ✅ Have 3-4 weeks for refactor
|
||||
|
||||
**Recommended Timeline:** Post-1.0 (January 2026)
|
||||
|
||||
---
|
||||
|
||||
## 💰 **Effort vs Value:**
|
||||
|
||||
### **Effort:** HIGH (3-4 weeks)
|
||||
### **Value:** MEDIUM (Better code quality)
|
||||
|
||||
**Conclusion:** Good for long-term, not critical for Beta/1.0
|
||||
|
||||
---
|
||||
|
||||
**Status:** 📋 **Planned for Post-1.0**
|
||||
**Priority:** 🟢 LOW (Quality of Life)
|
||||
**Estimated Time:** 3-4 weeks
|
||||
**Recommended:** After 1.0 release
|
||||
Reference in New Issue
Block a user