novafarma/docs/CHARACTER_SETUP_GUIDE.md

# 🎮 KRVAVA ŽETEV - Character Setup Guide

Vodič za ustvarjanje in dodajanje novih karakterjev v igro.

---

## 📋 Trenutne Nastavitve Igralca

### Player Character (Protagonist)
- **Sprite**: `assets/sprites/player_walking_clean.png`
- **Texture Key**: `player_protagonist`
- **Frame Size**: 256x256 pixels
- **Total Size**: 1024x1024 pixels (4x4 grid = 16 frames)
- **Scale**: 0.5 (prikazuje kot 128x128)
- **Origin**: (0.5, 1.0) - bottom center

### Animation Layout
```
Row 1 (frames 0-3):   DOWN  (spredaj, proti kameri)
Row 2 (frames 4-7):   LEFT  (levo, stranski pogled)
Row 3 (frames 8-11):  RIGHT (desno, stranski pogled)
Row 4 (frames 12-15): UP    (zadaj, hrbtni pogled)
```

### Animacije
- `protagonist_walk_down` - frames 0-3 @ 8 fps
- `protagonist_walk_left` - frames 4-7 @ 8 fps
- `protagonist_walk_right` - frames 8-11 @ 8 fps
- `protagonist_walk_up` - frames 12-15 @ 8 fps
- `protagonist_idle_down` - frame 0
- `protagonist_idle_left` - frame 4
- `protagonist_idle_right` - frame 8
- `protagonist_idle_up` - frame 12

---

## 🎨 Kako Ustvariti Nov Karakter

### 1. Pripravi Spritesheet Sliko

**Zahteve:**
- **Format**: PNG s transparentnim ozadjem
- **Velikost**: 1024x1024 pixels (ali 512x512 ali 2048x2048 - mora biti deljivo s 4)
- **Grid**: 4x4 (16 frames)
- **Frame Size**: 256x256 pixels (ali 128x128, 512x512)
- **Ozadje**: 100% transparentno (brez šahovnice!)

**Če imaš sliko s šahovnico**, uporabi Python script:
```bash
python tools/remove_checkerboard.py
```

### 2. Shrani Sliko v Pravilno Mapo

```
c:\novafarma\assets\sprites\[character_name]_walking.png
```

Primer:
- `zombie_walking.png`
- `merchant_walking.png`
- `knight_walking.png`

### 3. Dodaj v PreloadScene.js

Odpri: `c:\novafarma\src\scenes\PreloadScene.js`

**V preload() funkciji dodaj:**
```javascript
// Nov Karakter - [IME]
this.load.spritesheet('[character_key]', 'assets/sprites/[character_name]_walking.png', {
    frameWidth: 256,  // Nastavi glede na velikost frame-a
    frameHeight: 256
});
```

**V createAnimations() funkciji dodaj:**
```javascript
// [CHARACTER_NAME] Walking Animations
this.anims.create({
    key: '[character]_walk_down',
    frames: this.anims.generateFrameNumbers('[character_key]', { start: 0, end: 3 }),
    frameRate: 8,
    repeat: -1
});

this.anims.create({
    key: '[character]_walk_left',
    frames: this.anims.generateFrameNumbers('[character_key]', { start: 4, end: 7 }),
    frameRate: 8,
    repeat: -1
});

this.anims.create({
    key: '[character]_walk_right',
    frames: this.anims.generateFrameNumbers('[character_key]', { start: 8, end: 11 }),
    frameRate: 8,
    repeat: -1
});

this.anims.create({
    key: '[character]_walk_up',
    frames: this.anims.generateFrameNumbers('[character_key]', { start: 12, end: 15 }),
    frameRate: 8,
    repeat: -1
});

// Idle animations
this.anims.create({
    key: '[character]_idle_down',
    frames: [{ key: '[character_key]', frame: 0 }],
    frameRate: 1
});

this.anims.create({
    key: '[character]_idle_left',
    frames: [{ key: '[character_key]', frame: 4 }],
    frameRate: 1
});

this.anims.create({
    key: '[character]_idle_right',
    frames: [{ key: '[character_key]', frame: 8 }],
    frameRate: 1
});

this.anims.create({
    key: '[character]_idle_up',
    frames: [{ key: '[character_key]', frame: 12 }],
    frameRate: 1
});
```

### 4. Ustvari Character Class

Ustvari novo datoteko: `c:\novafarma\src\entities\[CharacterName].js`

**Template:**
```javascript
// [Character Name] Entity
class [ClassName] {
    constructor(scene, gridX, gridY, offsetX = 0, offsetY = 0) {
        this.scene = scene;
        this.gridX = gridX;
        this.gridY = gridY;
        this.offsetX = offsetX;
        this.offsetY = offsetY;
        
        this.iso = new IsometricUtils(48, 24);
        this.direction = 'down';
        this.isMoving = false;
        
        this.createSprite();
    }
    
    createSprite() {
        const screenPos = this.iso.toScreen(this.gridX, this.gridY);
        this.sprite = this.scene.add.sprite(
            screenPos.x + this.offsetX,
            screenPos.y + this.offsetY,
            '[character_key]',
            0
        );
        this.sprite.setOrigin(0.5, 1.0);
        this.sprite.setScale(0.5); // Nastavi glede na velikost
        
        // Play idle animation
        if (this.scene.anims.exists('[character]_idle_down')) {
            this.sprite.play('[character]_idle_down');
        }
    }
    
    update(delta) {
        // Add character logic here
    }
    
    destroy() {
        if (this.sprite) this.sprite.destroy();
    }
}
```

### 5. Dodaj v GameScene.js

```javascript
// Import character
// (če uporabljaš module system)

// V create() funkciji:
this.myCharacter = new [ClassName](this, 50, 50, this.terrainSystem.offsetX, this.terrainSystem.offsetY);

// V update() funkciji:
this.myCharacter.update(delta);
```

---

## 🛠️ Python Script za Odstranitev Šahovnice

**Lokacija:** `c:\novafarma\tools\remove_checkerboard.py`

**Uporaba:**
1. Odpri `remove_checkerboard.py`
2. Spremeni `input_file` in `output_file` pot
3. Zaženi: `python tools\remove_checkerboard.py`

**Primer:**
```python
input_file = r"C:\Users\Downloads\my_character.png"
output_file = r"c:\novafarma\assets\sprites\my_character_clean.png"
```

---

## ✅ Checklist za Nov Karakter

- [ ] Ustvari/pridobi spritesheet (1024x1024, 4x4 grid, transparentno ozadje)
- [ ] Odstrani šahovnico (če je potrebno)
- [ ] Shrani v `assets/sprites/`
- [ ] Dodaj spritesheet load v `PreloadScene.js`
- [ ] Dodaj animacije v `PreloadScene.js`
- [ ] Ustvari Character class (opcijsko)
- [ ] Dodaj v `GameScene.js` (opcijsko)
- [ ] Testiraj v igri (osveži s Ctrl+R)

---

## 📐 Velikosti & Skale

| Frame Size | Total Size | Priporočen Scale | Display Size |
|------------|------------|------------------|--------------|
| 128x128    | 512x512    | 1.0              | 128x128      |
| 256x256    | 1024x1024  | 0.5              | 128x128      |
| 512x512    | 2048x2048  | 0.25             | 128x128      |

---

## 🎯 Priporočila

1. **Consistent Size**: Vsi karakterji naj imajo enako display velikost (128x128)
2. **Transparent Background**: Vedno uporabi PNG s 100% transparentnim ozadjem
3. **Frame Rate**: 8 fps je idealno za walking animacije
4. **Origin Point**: (0.5, 1.0) za bottom-center je najboljše za isometric igre
5. **Backup**: Vedno shrani original pred odstranjevanjem šahovnice

---

**Zadnja posodobitev:** 14.12.2025
**Avtor:** KRVAVA ŽETEV Team