From dec5d652b45fd4a4af07164ad9b957611f4e1ebd Mon Sep 17 00:00:00 2001 From: Vladimir nett00n Budylnikov Date: Wed, 24 Sep 2025 11:19:00 +0400 Subject: [PATCH] include info about asset sources file --- assets/sources.yaml | 424 ++++++++++++++++++++++++++++++++++++++++ data/sources.yaml | 11 -- docs/CLAUDE.md | 26 +++ docs/CODE_OF_CONDUCT.md | 44 +++++ docs/MAP.md | 36 +++- 5 files changed, 529 insertions(+), 12 deletions(-) create mode 100644 assets/sources.yaml delete mode 100644 data/sources.yaml diff --git a/assets/sources.yaml b/assets/sources.yaml new file mode 100644 index 0000000..4a49092 --- /dev/null +++ b/assets/sources.yaml @@ -0,0 +1,424 @@ +# Asset Attribution and Source Information +# Every asset in this project must be documented here with complete metadata +# Required fields: source, license, attribution, modifications, usage + +audio: + music: + "Space Horror InGame Music (Exploration) _Clement Panchout.wav": + source: "https://clement-panchout.itch.io/yet-another-free-music-pack" + license: "" # TODO: Verify license from source + attribution: "Space Horror InGame Music by Clement Panchout" + modifications: "Converted to WAV format, loop configuration applied in AudioManager" + usage: "Background music for all gameplay scenes and menus" + + sfx: + "817587__silverdubloons__tick06.wav": + source: "https://freesound.org/people/SilverDubloons/sounds/817587/" + license: "" # TODO: Verify license from freesound.org + attribution: "Tick06 by SilverDubloons" + modifications: "None" + usage: "UI button click sound effects throughout the application" + +sprites: + characters: + skeleton: + "Skeleton Attack.png": + source: "https://jesse-m.itch.io/skeleton-pack" + license: "" # TODO: Verify license from itch.io page + attribution: "Skeleton Pack by Jesse M" + modifications: "" + usage: "Skeleton character attack animation sprite" + + "Skeleton Dead.png": + source: "https://jesse-m.itch.io/skeleton-pack" + license: "" # TODO: Verify license from itch.io page + attribution: "Skeleton Pack by Jesse M" + modifications: "" + usage: "Skeleton character death animation sprite" + + "Skeleton Hit.png": + source: "https://jesse-m.itch.io/skeleton-pack" + license: "" # TODO: Verify license from itch.io page + attribution: "Skeleton Pack by Jesse M" + modifications: "" + usage: "Skeleton character hit reaction animation sprite" + + "Skeleton Idle.png": + source: "https://jesse-m.itch.io/skeleton-pack" + license: "" # TODO: Verify license from itch.io page + attribution: "Skeleton Pack by Jesse M" + modifications: "" + usage: "Skeleton character idle animation sprite" + + "Skeleton React.png": + source: "https://jesse-m.itch.io/skeleton-pack" + license: "" # TODO: Verify license from itch.io page + attribution: "Skeleton Pack by Jesse M" + modifications: "" + usage: "Skeleton character reaction animation sprite" + + "Skeleton Walk.png": + source: "https://jesse-m.itch.io/skeleton-pack" + license: "" # TODO: Verify license from itch.io page + attribution: "Skeleton Pack by Jesse M" + modifications: "" + usage: "Skeleton character walking animation sprite" + + gems: + # Blue gems + "bg_08.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Blue gem sprite for Match-3 gameplay" + + "bg_16a.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Blue gem variant sprite for Match-3 gameplay" + + "bg_19.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Blue gem variant sprite for Match-3 gameplay" + + "bg_26.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Blue gem variant sprite for Match-3 gameplay" + + "bg_27.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Blue gem variant sprite for Match-3 gameplay" + + "bg_28.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Blue gem variant sprite for Match-3 gameplay" + + # Dark/Gray gems + "dg_08.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Dark gem sprite for Match-3 gameplay" + + "dg_16a.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Dark gem variant sprite for Match-3 gameplay" + + "dg_19.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Dark gem variant sprite for Match-3 gameplay" + + "dg_26.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Dark gem variant sprite for Match-3 gameplay" + + "dg_27.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Dark gem variant sprite for Match-3 gameplay" + + "dg_28.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Dark gem variant sprite for Match-3 gameplay" + + # Green gems + "gg_08.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Green gem sprite for Match-3 gameplay" + + "gg_16a.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Green gem variant sprite for Match-3 gameplay" + + "gg_19.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Green gem variant sprite for Match-3 gameplay" + + "gg_26.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Green gem variant sprite for Match-3 gameplay" + + "gg_27.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Green gem variant sprite for Match-3 gameplay" + + "gg_28.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Green gem variant sprite for Match-3 gameplay" + + # Magenta gems + "mg_08.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Magenta gem sprite for Match-3 gameplay" + + "mg_16a.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Magenta gem variant sprite for Match-3 gameplay" + + "mg_19.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Magenta gem variant sprite for Match-3 gameplay" + + "mg_26.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Magenta gem variant sprite for Match-3 gameplay" + + "mg_27.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Magenta gem variant sprite for Match-3 gameplay" + + "mg_28.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Magenta gem variant sprite for Match-3 gameplay" + + # Purple gems + "pg_08.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Purple gem sprite for Match-3 gameplay" + + "pg_16a.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Purple gem variant sprite for Match-3 gameplay" + + "pg_19.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Purple gem variant sprite for Match-3 gameplay" + + "pg_26.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Purple gem variant sprite for Match-3 gameplay" + + "pg_27.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Purple gem variant sprite for Match-3 gameplay" + + "pg_28.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Purple gem variant sprite for Match-3 gameplay" + + # Red gems + "rg_08.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Red gem sprite for Match-3 gameplay" + + "rg_16a.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Red gem variant sprite for Match-3 gameplay" + + "rg_19.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Red gem variant sprite for Match-3 gameplay" + + "rg_26.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Red gem variant sprite for Match-3 gameplay" + + "rg_27.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Red gem variant sprite for Match-3 gameplay" + + "rg_28.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Red gem variant sprite for Match-3 gameplay" + + # Silver gems + "sg_08.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Silver gem sprite for Match-3 gameplay" + + "sg_16a.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Silver gem variant sprite for Match-3 gameplay" + + "sg_19.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Silver gem variant sprite for Match-3 gameplay" + + "sg_26.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Silver gem variant sprite for Match-3 gameplay" + + "sg_27.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Silver gem variant sprite for Match-3 gameplay" + + "sg_28.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Silver gem variant sprite for Match-3 gameplay" + + # Yellow gems + "yg_08.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Yellow gem sprite for Match-3 gameplay" + + "yg_16a.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Yellow gem variant sprite for Match-3 gameplay" + + "yg_19.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Yellow gem variant sprite for Match-3 gameplay" + + "yg_26.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Yellow gem variant sprite for Match-3 gameplay" + + "yg_27.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Yellow gem variant sprite for Match-3 gameplay" + + "yg_28.png": + source: "https://ilustragm.itch.io/gems-icon-01-free" + license: "" # TODO: Verify license from itch.io page + attribution: "Gems Icon 01 Free by IlustraGM" + modifications: "" + usage: "Yellow gem variant sprite for Match-3 gameplay" + +# Referenced in original sources.yaml but file not found: +# textures: +# backgrounds: +# "beanstalk-dark.webp": +# source: "https://www.toptal.com/designers/subtlepatterns/beanstalk-dark-pattern/" +# license: "" # TODO: Verify license and locate file +# attribution: "Beanstalk Dark pattern from Subtle Patterns" +# modifications: "" +# usage: "Background texture (file location TBD)" + +# TODO: Verify all license information by visiting source URLs +# TODO: Check for any missing assets not documented here +# TODO: Confirm all attribution text meets source requirements \ No newline at end of file diff --git a/data/sources.yaml b/data/sources.yaml deleted file mode 100644 index 894051c..0000000 --- a/data/sources.yaml +++ /dev/null @@ -1,11 +0,0 @@ ---- -- fileName: assets/audio/music/Space Horror InGame Music (Exploration) _Clement Panchout.wav - commonUrl: https://clement-panchout.itch.io/yet-another-free-music-pack -- fileName: assets/audio/sfx/817587__silverdubloons__tick06.wav - commonUrl: https://freesound.org/people/SilverDubloons/sounds/817587/ -- fileName: assets/textures/backgrounds/beanstalk-dark.webp - commonUrl: https://www.toptal.com/designers/subtlepatterns/beanstalk-dark-pattern/ -- fileName: assets/sprites/characters/skeleton - commonUrl: https://jesse-m.itch.io/skeleton-pack -- fileName: assets/sprites/gems - commonUrl: https://ilustragm.itch.io/gems-icon-01-free diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md index 1fed281..cd0e49f 100644 --- a/docs/CLAUDE.md +++ b/docs/CLAUDE.md @@ -34,6 +34,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co - Currently supports English and Russian - New translations: Add to `project.godot` internationalization section +### Asset Management +- **CRITICAL**: Every asset must be documented in `assets/sources.yaml` before committing +- Include source, license, attribution, modifications, and usage information +- Verify license compatibility with project requirements +- Commit asset files and sources.yaml together in the same commit + ## Key Development Guidelines ### Scene Management @@ -82,6 +88,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co 1. Check `docs/MAP.md` for architecture understanding 2. Review `docs/CODE_OF_CONDUCT.md` for coding standards 3. Understand existing patterns before implementing new features +4. If adding assets, prepare `assets/sources.yaml` documentation ### Testing Changes - Run project with F5 in Godot Editor @@ -112,3 +119,22 @@ DebugManager.log_error("Failed to load audio resource: " + audio_path, "AudioMan print("debug") # Use structured logging instead push_error("error") # Use DebugManager.log_error() with category ``` + +### Asset Management Workflow +```yaml +# ✅ Required assets/sources.yaml entry format +audio: + music: + "background_music.ogg": + source: "https://freesound.org/people/artist/sounds/123456/" + license: "CC BY 4.0" + attribution: "Background Music by Artist Name" + modifications: "Converted to OGG, adjusted volume" + usage: "Main menu and gameplay background music" + +# ✅ Proper commit workflow +# 1. Add asset to appropriate assets/ subdirectory +# 2. Update assets/sources.yaml with complete metadata +# 3. git add both files together +# 4. Commit with descriptive message including attribution +``` diff --git a/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md index c4db700..40af68c 100644 --- a/docs/CODE_OF_CONDUCT.md +++ b/docs/CODE_OF_CONDUCT.md @@ -159,6 +159,30 @@ push_error("error") # Use DebugManager.log_error() with context if debug_mode: print("debug info") # Use DebugManager.log_debug() ``` +### Asset Management +- **MANDATORY**: Every asset added to the project must be documented in `assets/sources.yaml` +- Include complete source information, license details, and attribution requirements +- Document any modifications made to original assets +- Verify license compatibility with project usage before adding assets +- Update sources.yaml in the same commit as adding the asset + +```gdscript +# ✅ Correct asset addition workflow +# 1. Add asset file to appropriate assets/ subdirectory +# 2. Update assets/sources.yaml with complete metadata +# 3. Commit both files together with descriptive message + +# Example sources.yaml entry: +# audio: +# sfx: +# "button_click.wav": +# source: "https://freesound.org/people/user/sounds/12345/" +# license: "CC BY 3.0" +# attribution: "Button Click by SoundArtist" +# modifications: "Normalized volume, trimmed silence" +# usage: "UI button interactions" +``` + ### Error Handling - Always check if resources loaded successfully - Use `DebugManager.log_error()` for critical failures @@ -257,6 +281,26 @@ node.do_something() # Could crash if node doesn't exist # Use autoloads instead ``` +### Asset Management Violations +```gdscript +# ❌ Don't add assets without documentation +# Adding audio/new_music.mp3 without updating sources.yaml + +# ❌ Don't use assets without verifying licenses +# Using copyrighted music without permission + +# ❌ Don't modify assets without documenting changes +# Editing sprites without noting modifications in sources.yaml + +# ❌ Don't commit assets and documentation separately +git add assets/sprites/new_sprite.png +git commit -m "add sprite" # Missing sources.yaml update + +# ✅ Correct approach +git add assets/sprites/new_sprite.png assets/sources.yaml +git commit -m "add new sprite with attribution" +``` + ### Performance Issues ```gdscript # ❌ Don't search nodes repeatedly diff --git a/docs/MAP.md b/docs/MAP.md index 42d7968..f81d7c7 100644 --- a/docs/MAP.md +++ b/docs/MAP.md @@ -165,13 +165,46 @@ audio/ ### Visual Assets (`assets/`) ``` assets/ +├── audio/ +│ ├── music/ # Background music files +│ └── sfx/ # Sound effects ├── sprites/ │ ├── characters/skeleton/ # Character artwork │ ├── gems/ # Match-3 gem sprites │ └── ui/ # User interface elements ├── textures/ │ └── backgrounds/ # Background images -└── fonts/ # Custom fonts +├── fonts/ # Custom fonts +└── sources.yaml # Asset metadata and attribution +``` + +### Asset Management (`assets/sources.yaml`) +**REQUIRED**: Every asset added to the project must be documented in `assets/sources.yaml` with: +- **Source information** - Where the asset came from (URL, artist, store, etc.) +- **License details** - Usage rights, attribution requirements, commercial permissions +- **Attribution text** - Exact text to use for credits if required +- **Modification notes** - Any changes made to the original asset +- **Usage context** - Where and how the asset is used in the project + +**Example format:** +```yaml +audio: + music: + "Space Horror InGame Music (Exploration) _Clement Panchout.wav": + source: "https://freesound.org/people/ClementPanchout/" + license: "CC BY 4.0" + attribution: "Space Horror InGame Music by Clement Panchout" + modifications: "Converted to WAV, loop points adjusted" + usage: "Background music for all gameplay scenes" + +sprites: + gems: + "gem_blue.png": + source: "Created in-house" + license: "Project proprietary" + attribution: "Skelly development team" + modifications: "None" + usage: "Match-3 blue gem sprite" ``` ## Data & Configuration @@ -229,6 +262,7 @@ Game --> scenes/game/gameplays/match3_gameplay.tscn, clickomania_gameplay.tscn AudioManager --> assets/audio/music/ SettingsManager --> localization/languages.json AudioManager --> data/default_bus_layout.tres +Asset Management --> assets/sources.yaml (required for all assets) ``` ## Logging System