novo

backup_faza11_extracted/backup_faza11_2025-12-11/PLAYER_DATA_API.md

@@ -0,0 +1,296 @@
+# 🎮 Player Data & Active Item System
+
+**File:** `src/core/player.js`  
+**Updated:** 10.12.2025
+
+---
+
+## 📦 **Nove Funkcije za Active Item**
+
+Dodane čiste helper funkcije za delo z igralčevim aktivnim itemom (trenutno selected slot).
+
+---
+
+## 🔧 **API Reference**
+
+### **1. getPlayerActiveItem(playerOrScene)**
+Pridobi trenutno aktivni item.
+
+```javascript
+import { getPlayerActiveItem } from './core/player.js';
+
+const activeItem = getPlayerActiveItem(player);
+// Returns: { type: 'axe', count: 1 } or null
+```
+
+---
+
+### **2. getPlayerActiveItemType(playerOrScene)**
+Pridobi samo tip aktivnega itema.
+
+```javascript
+import { getPlayerActiveItemType } from './core/player.js';
+
+const itemType = getPlayerActiveItemType(scene);
+// Returns: 'axe' or null
+```
+
+---
+
+### **3. hasPlayerActiveItem(playerOrScene, itemType)**
+Preveri ali ima igralec specifičen item aktiven.
+
+```javascript
+import { hasPlayerActiveItem } from './core/player.js';
+
+if (hasPlayerActiveItem(player, 'seeds')) {
+    console.log('Player has seeds selected!');
+}
+```
+
+---
+
+### **4. isPlayerActiveItemTool(playerOrScene)**
+Preveri ali je aktivni item orodje.
+
+```javascript
+import { isPlayerActiveItemTool } from './core/player.js';
+
+if (isPlayerActiveItemTool(scene)) {
+    // Show tool animation
+}
+```
+
+**Tool Types:**
+- `axe`
+- `pickaxe`
+- `hoe`
+- `sword`
+- `fishing_rod`
+- `watering_can`
+
+---
+
+### **5. consumePlayerActiveItem(playerOrScene, amount)**
+Porabi aktivni item (npr. za seeds).
+
+```javascript
+import { consumePlayerActiveItem } from './core/player.js';
+
+// Plant seed
+if (hasPlayerActiveItem(player, 'seeds')) {
+    consumePlayerActiveItem(player, 1);
+    console.log('Seed used!');
+}
+```
+
+---
+
+### **6. getPlayerData(player)**
+Pridobi vse igralčeve podatke v enem objektu.
+
+```javascript
+import { getPlayerData } from './core/player.js';
+
+const playerData = getPlayerData(player);
+
+console.log(playerData);
+/*
+{
+    // Position
+    gridX: 50,
+    gridY: 50,
+    x: 1200,
+    y: 800,
+    
+    // Stats
+    hp: 85,
+    maxHp: 100,
+    energy: 70,
+    maxEnergy: 100,
+    
+    // Progression
+    level: 3,
+    xp: 150,
+    xpToNextLevel: 225,
+    
+    // State
+    isDead: false,
+    isMoving: false,
+    direction: 'down',
+    lastDir: { x: 0, y: 1 },
+    
+    // Active item
+    activeItem: { type: 'axe', count: 1 },
+    activeItemType: 'axe',
+    activeItemCount: 1
+}
+*/
+```
+
+---
+
+## 💡 **Primeri Uporabe**
+
+### **Primer 1: Farming System**
+```javascript
+import { hasPlayerActiveItem, consumePlayerActiveItem } from './core/player.js';
+
+function tryPlantCrop(scene, gridX, gridY) {
+    // Check if player has seeds
+    if (!hasPlayerActiveItem(scene, 'seeds')) {
+        console.log('⚠️ No seeds!');
+        return false;
+    }
+    
+    // Plant crop
+    scene.farmingSystem.plantCrop(gridX, gridY, 'wheat');
+    
+    // Consume seed
+    consumePlayerActiveItem(scene, 1);
+    
+    return true;
+}
+```
+
+---
+
+### **Primer 2: Building System**
+```javascript
+import { getPlayerActiveItem } from './core/player.js';
+
+function tryPlaceBuilding(scene, gridX, gridY) {
+    const activeItem = getPlayerActiveItem(scene);
+    
+    if (!activeItem) {
+        console.log('⚠️ No item selected');
+        return false;
+    }
+    
+    // Check if item is buildable
+    const buildableItems = ['fence', 'chest', 'furnace'];
+    
+    if (!buildableItems.includes(activeItem.type)) {
+        console.log(`⚠️ ${activeItem.type} cannot be placed`);
+        return false;
+    }
+    
+    // Place building
+    scene.buildingSystem.placeBuilding(activeItem.type, gridX, gridY);
+    
+    // Remove from inventory
+    scene.inventorySystem.removeItem(activeItem.type, 1);
+    
+    return true;
+}
+```
+
+---
+
+### **Primer 3: Combat System**
+```javascript
+import { isPlayerActiveItemTool, getPlayerActiveItemType } from './core/player.js';
+
+function calculatePlayerDamage(player) {
+    let baseDamage = 5;
+    
+    if (isPlayerActiveItemTool(player)) {
+        const toolType = getPlayerActiveItemType(player);
+        
+        switch (toolType) {
+            case 'sword':
+                baseDamage = 20;
+                break;
+            case 'axe':
+                baseDamage = 10;
+                break;
+            case 'pickaxe':
+                baseDamage = 8;
+                break;
+            default:
+                baseDamage = 5;
+        }
+    }
+    
+    return baseDamage;
+}
+```
+
+---
+
+### **Primer 4: UI Display**
+```javascript
+import { getPlayerData } from './core/player.js';
+
+function updatePlayerUI(player) {
+    const data = getPlayerData(player);
+    
+    // Update health bar
+    const hpPercent = (data.hp / data.maxHp) * 100;
+    healthBar.setPercent(hpPercent);
+    
+    // Update level text
+    levelText.setText(`Level ${data.level}`);
+    
+    // Update XP bar
+    const xpPercent = (data.xp / data.xpToNextLevel) * 100;
+    xpBar.setPercent(xpPercent);
+    
+    // Show active item
+    if (data.activeItem) {
+        activeItemIcon.setTexture(`item_${data.activeItemType}`);
+        activeItemCount.setText(data.activeItemCount);
+    } else {
+        activeItemIcon.setVisible(false);
+    }
+}
+```
+
+---
+
+## 🎯 **Migration Guide**
+
+### **Before (Old Way):**
+```javascript
+// Old: Direct UI access
+const uiScene = this.scene.get('UIScene');
+const selectedIdx = uiScene.selectedSlot;
+const slot = this.inventorySystem.slots[selectedIdx];
+
+if (slot && slot.type === 'seeds') {
+    // Do something
+}
+```
+
+### **After (New Way):**
+```javascript
+// New: Clean helper function
+import { hasPlayerActiveItem } from './core/player.js';
+
+if (hasPlayerActiveItem(this, 'seeds')) {
+    // Do something
+}
+```
+
+---
+
+## 📊 **Benefits**
+
+✅ **Cleaner Code** - `hasPlayerActiveItem(player, 'seeds')` vs manual slot checking  
+✅ **Centralized Logic** - One place to update if inventory system changes  
+✅ **Type Safety** - Functions validate inputs  
+✅ **Flexibility** - Works with both `player` instance and `scene`  
+✅ **Complete Data** - `getPlayerData()` gives everything in one call  
+
+---
+
+## 🔄 **Integration with Existing Code**
+
+Vse funkcije delujejo z obstoječim sistemom - samo wrappajo UIScene.selectedSlot logiko v čiste funkcije.
+
+**No breaking changes!** Stara koda še vedno dela.
+
+---
+
+**Status:** ✅ **Ready to use!**  
+**Location:** `src/core/player.js` & `src/core/index.js`