cirnogodot/Scripts/Editor/CreateWeapon3D_README.md

# Create Weapon 3D - EditorScript

## Overview

This GDScript EditorScript automates the creation of a new 3D weapon with all required resources in the Cirno project. It handles the tedious process of creating and linking multiple resource files.

## What It Creates

When you run this script, it will automatically:

1. **Create a WeaponResource** (`res://Resources/Weapons/[WEAPON_KEY].tres`)
   - Sets up basic weapon stats (rate of fire, ammo capacity, etc.)
   - Links to the default bullet resource
   - Configures weapon properties

2. **Create a LootItem resource** (`res://Resources/Items/[WEAPON_KEY]_Item.tres`)
   - Links to the WeaponResource
   - Sets item type to "Weapon"
   - Configures the drop scene path to `GenericItem3D.tscn`

3. **Add to ItemsDatabase** (`res://Resources/ItemsDatabase.tres`)
   - Automatically appends the new item to the end of the database list

## How to Use

### Method 1: Using the Script Editor

1. Open `Scripts/Editor/CreateWeapon3D.gd` in the Godot Script Editor
2. Modify the configuration variables at the top of the `_run()` function:
   ```gdscript
   var weapon_name = "My Awesome Gun"
   var weapon_item_key = "AWESOME_GUN"
   var weapon_short_name = "AG-1"
   var weapon_description = "An amazing weapon that shoots cool projectiles"
   ```
3. Go to **File > Run** in the menu (or press `Ctrl+Shift+X`)
4. Check the Output panel for success messages

### Method 2: From the Command Line

You can also run the script from the command line using the Godot executable:

```bash
godot --editor --script Scripts/Editor/CreateWeapon3D.gd --quit
```

## Configuration Variables

Edit these variables in the `_run()` function before running:

| Variable | Description | Example |
|----------|-------------|---------|
| `weapon_name` | Display name of the weapon | `"Plasma Rifle"` |
| `weapon_item_key` | Unique identifier (uppercase with underscores) | `"PLASMA_RIFLE"` |
| `weapon_short_name` | Short abbreviation shown in UI | `"PR-5"` |
| `weapon_description` | Description text for the weapon | `"Fires superheated plasma bolts"` |

## Default Weapon Stats

The script creates weapons with these default values (you can modify them in the created resource afterwards):

- **BulletData**: `res://Resources/Bullets/simple_ice_bullet.tres`
- **AmmoKey**: `BATTERY`
- **Priority**: `10`
- **AmmoPerShot**: `1`
- **RateOfFire**: `0.2` seconds
- **BulletCapacity**: `50`
- **ReloadTime**: `1.0` seconds
- **InfiniteAmmo**: `false`
- **AutoReload**: `true`
- **RechargeTime**: `0.5` seconds
- **RechargeAmount**: `5`
- **BulletsPerShot**: `1`
- **SpreadAngle**: `0.0`
- **RandomSpread**: `0.0`

## Post-Creation Steps

After running the script, you should:

1. **Open the WeaponResource** (`res://Resources/Weapons/[WEAPON_KEY].tres`)
   - Adjust weapon stats to match your design
   - Change the bullet type if needed
   - Add reload and shoot sounds

2. **Open the LootItem** (`res://Resources/Items/[WEAPON_KEY]_Item.tres`)
   - Add an inventory sprite texture
   - Set the price if applicable
   - Configure pickup behavior

3. **Test the weapon** by adding it to a test scene or using the debug menu

## Troubleshooting

### "WeaponResource already exists"
- The script checks if files already exist to prevent overwriting
- Delete the existing files first or choose a different weapon key

### "Could not load WeaponResource.cs script"
- Ensure the C# scripts are properly compiled
- Check that `res://Scripts/Resources/WeaponResource.cs` exists

### "Could not load bullet resource"
- Verify that `res://Resources/Bullets/simple_ice_bullet.tres` exists
- Or change `default_bullet_path` to point to a different bullet resource

### Changes not appearing in editor
- Save the project (`Ctrl+S`)
- Reimport resources if needed
- Restart Godot editor if issues persist

## Technical Details

### Resource Script Classes Used

- **WeaponResource**: C# class that defines weapon properties and behavior
- **LootItem**: C# class that represents items in the game's inventory system
- **ItemsDatabase**: C# class that holds all game items in a centralized list

### Item Type Enum

The script sets the Item property to `13`, which corresponds to `ItemTypes.Weapon` in the C# enum:

```csharp
public enum ItemTypes {
    // ... other types ...
    Weapon,  // Index 13
    // ... more types ...
}
```

## Customization

You can modify the script to:

- Change default weapon stats
- Use a different default bullet resource
- Create multiple weapons at once (by calling the functions in a loop)
- Add additional properties to the created resources

## Example Output

```
=== Starting Weapon Creation ===
Weapon Name: Plasma Rifle
Item Key: PLASMA_RIFLE
✓ Created WeaponResource at: res://Resources/Weapons/PLASMA_RIFLE.tres
✓ Created LootItem at: res://Resources/Items/PLASMA_RIFLE_Item.tres
✓ Added to ItemsDatabase
=== Weapon Creation Complete ===
Remember to:
1. Set appropriate weapon stats in res://Resources/Weapons/PLASMA_RIFLE.tres
2. Add a sprite texture to the LootItem in res://Resources/Items/PLASMA_RIFLE_Item.tres
3. Save all modified resources
```

## Notes

- This script is designed for 3D weapons specifically
- The script uses `@tool` annotation to run in the editor
- All paths use Godot's `res://` protocol for project-relative paths
- The script performs safety checks to prevent overwriting existing files

## Support

If you encounter issues:
1. Check the Godot Output panel for detailed error messages
2. Verify all C# scripts are compiled without errors
3. Ensure all referenced resources exist at their expected paths