From db4f3166c248ec2b1e7013543ef12330b0fcd7ae Mon Sep 17 00:00:00 2001 From: Throwing Date: Sun, 26 Jul 2026 14:56:01 +0800 Subject: [PATCH 1/3] Prepare ShadowPets for public reuse --- .github/ISSUE_TEMPLATE/asset-problem.yml | 48 +++ .github/ISSUE_TEMPLATE/config.yml | 8 + .github/ISSUE_TEMPLATE/pet-request.yml | 31 ++ .github/PULL_REQUEST_TEMPLATE.md | 15 + .github/workflows/assets.yml | 35 +++ .github/workflows/release.yml | 44 +++ .gitignore | 2 + ATTRIBUTION.md | 12 + CONTRIBUTING.md | 26 ++ LICENSE | 43 +++ LICENSE-ASSETS.md | 43 +++ README.md | 168 ++++++----- index.html | 66 +++- requirements-dev.txt | 1 + social-preview.png | Bin 0 -> 70524 bytes tools/build_animations.py | 51 +++- tools/make_social_preview.py | 70 +++++ tools/package_release.py | 146 +++++++++ tools/validate_assets.py | 367 +++++++++++++++++++++++ 19 files changed, 1093 insertions(+), 83 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/asset-problem.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/pet-request.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/workflows/assets.yml create mode 100644 .github/workflows/release.yml create mode 100644 ATTRIBUTION.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 LICENSE-ASSETS.md create mode 100644 requirements-dev.txt create mode 100644 social-preview.png create mode 100644 tools/make_social_preview.py create mode 100644 tools/package_release.py create mode 100644 tools/validate_assets.py diff --git a/.github/ISSUE_TEMPLATE/asset-problem.yml b/.github/ISSUE_TEMPLATE/asset-problem.yml new file mode 100644 index 0000000..f86d0ba --- /dev/null +++ b/.github/ISSUE_TEMPLATE/asset-problem.yml @@ -0,0 +1,48 @@ +name: Asset problem +description: Report a broken file, visual defect, import issue, or gallery problem. +title: "[Asset]: " +labels: [bug] +body: + - type: markdown + attributes: + value: Thanks for helping keep the ShadowPets pack game-ready. Please identify the exact pet and file whenever possible. + - type: dropdown + id: area + attributes: + label: Area + options: + - Static PNG + - Animation PNG frames + - Animated GIF + - Packed sprite sheet + - Motion Lab website + - Release ZIP or checksum + - Documentation or license + validations: + required: true + - type: input + id: asset + attributes: + label: Pet or file path + placeholder: ShadowPets/Luna.png or ShadowPets/Animations/Luna/greet.gif + - type: textarea + id: problem + attributes: + label: What happened? + description: Include the engine/browser, import settings, expected result, and actual result. + validations: + required: true + - type: textarea + id: evidence + attributes: + label: Screenshot or minimal reproduction + description: Drag in a screenshot, project snippet, or steps that reproduce the problem. + - type: checkboxes + id: checks + attributes: + label: Quick checks + options: + - label: I checked the live Motion Lab and the problem is still present. + required: true + - label: I searched existing issues for the same problem. + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..a6769b3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Preview the complete pack + url: https://throwingogo-hub.github.io/DigitalPets/ + about: Check all 30 loops and three backdrop modes before reporting a visual issue. + - name: Reuse and attribution guide + url: https://github.com/throwingogo-hub/DigitalPets/blob/main/LICENSE-ASSETS.md + about: See what CC BY 4.0 allows and copy the practical credit text. diff --git a/.github/ISSUE_TEMPLATE/pet-request.yml b/.github/ISSUE_TEMPLATE/pet-request.yml new file mode 100644 index 0000000..50f3242 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/pet-request.yml @@ -0,0 +1,31 @@ +name: New pet request +description: Propose a species or a small, reusable animation for a future pack update. +title: "[Request]: " +labels: [enhancement] +body: + - type: input + id: species + attributes: + label: Species or motion + placeholder: Moth companion or sleep loop + validations: + required: true + - type: textarea + id: use + attributes: + label: Where would this be useful? + description: Describe the game/UI context and why the existing ten pets or three motions do not cover it. + validations: + required: true + - type: textarea + id: constraints + attributes: + label: Silhouette or motion constraints + description: Note readability, anatomy, loop, or engine constraints—not a redesign of the shared ShadowPets style. + - type: checkboxes + id: license + attributes: + label: Licensing + options: + - label: I understand accepted visual contributions must be releasable under CC BY 4.0. + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..8167657 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,15 @@ +## What changed + + + +## Validation + +- [ ] I ran `python tools/validate_assets.py --check-rebuild --check-package`. +- [ ] The Motion Lab still works at narrow and wide viewport sizes. +- [ ] I did not regenerate or rewrite approved pet art unintentionally. +- [ ] New visual work can be released under CC BY 4.0; code/docs can be released under MIT. +- [ ] Counts, import guidance, license text, and screenshots are updated if the public pack changed. + +## Visual evidence + + diff --git a/.github/workflows/assets.yml b/.github/workflows/assets.yml new file mode 100644 index 0000000..834a337 --- /dev/null +++ b/.github/workflows/assets.yml @@ -0,0 +1,35 @@ +name: Asset checks + +on: + push: + branches: [main] + pull_request: + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: asset-checks-${{ github.ref }} + cancel-in-progress: true + +jobs: + validate: + name: Validate pack and deterministic release + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.12" + cache: pip + + - name: Install validator dependencies + run: python -m pip install -r requirements-dev.txt + + - name: Validate assets, site, rebuild, and package + run: python tools/validate_assets.py --check-rebuild --check-package diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..2fd2ae8 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,44 @@ +name: Publish asset pack + +on: + push: + tags: + - "v*" + +permissions: + contents: write + +jobs: + release: + name: Verify and attach ShadowPets.zip + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - name: Check out tagged source + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.12" + cache: pip + + - name: Install validator dependencies + run: python -m pip install -r requirements-dev.txt + + - name: Validate tagged pack + run: python tools/validate_assets.py --check-rebuild --check-package + + - name: Build deterministic release files + run: python tools/package_release.py --output dist + + - name: Create release or replace its assets + env: + GH_TOKEN: ${{ github.token }} + RELEASE_TAG: ${{ github.ref_name }} + run: | + if gh release view "$RELEASE_TAG" >/dev/null 2>&1; then + gh release upload "$RELEASE_TAG" dist/ShadowPets.zip dist/ShadowPets.zip.sha256 --clobber + else + gh release create "$RELEASE_TAG" dist/ShadowPets.zip dist/ShadowPets.zip.sha256 --generate-notes --title "ShadowPets $RELEASE_TAG" + fi diff --git a/.gitignore b/.gitignore index c5eb462..7182a53 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,4 @@ tmp/ .DS_Store +dist/ +__pycache__/ diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md new file mode 100644 index 0000000..cb19465 --- /dev/null +++ b/ATTRIBUTION.md @@ -0,0 +1,12 @@ +# Attribution + +Copy this line into your game's credits, README, or asset-credits file: + +> ShadowPets by throwingogo-hub — https://github.com/throwingogo-hub/DigitalPets — licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). + +If you changed the artwork, say so. For example: + +> Based on ShadowPets by throwingogo-hub — https://github.com/throwingogo-hub/DigitalPets — modified by Example Studio, licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). + +See [`LICENSE-ASSETS.md`](LICENSE-ASSETS.md) for the full scope and practical +reuse guidance. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1df18b4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,26 @@ +# Contributing to ShadowPets + +Bug reports, import notes, and focused fixes are welcome. Use the asset-problem +issue form for a broken sprite, loop, packed sheet, gallery interaction, release +archive, or documentation link. Use the request form for a future species or +motion with a concrete game use case. + +## Before opening a pull request + +1. Install the pinned developer dependency with + `python3 -m pip install -r requirements-dev.txt`. +2. Keep the ten approved static sprites and their animation art unchanged unless + the issue explicitly calls for a reviewed visual correction. +3. Run `python3 tools/validate_assets.py --check-rebuild --check-package`. +4. Open `index.html` through a local static server and check the affected + interaction at phone and desktop widths. + +The validator rebuilds derived animations and release archives in temporary +directories. It compares bytes without mutating tracked visual assets. + +## Licensing contributions + +By contributing code or documentation, you agree that it may be distributed +under the repository's MIT License. Only submit original visual work you have +the right to license under CC BY 4.0, because accepted ShadowPets visual assets +are distributed under that license. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..f71b10e --- /dev/null +++ b/LICENSE @@ -0,0 +1,43 @@ +ShadowPets is offered under two licenses, depending on what you use. + +Visual assets +------------- + +All image assets in ShadowPets/ and social-preview.png are licensed under the +Creative Commons Attribution 4.0 International license (CC BY 4.0): + +https://creativecommons.org/licenses/by/4.0/ + +This includes the ten static pet PNGs, animation frames, GIFs, packed sheets, +and preserved source sheets. You may copy, modify, and use these assets in +commercial or non-commercial games and projects, provided you give appropriate +credit. See LICENSE-ASSETS.md for the exact scope and practical attribution. + +Code and documentation +---------------------- + +All source code, automation, gallery HTML/CSS/JavaScript, workflows, templates, +and documentation in this repository are licensed under the MIT License below. +The MIT License does not replace the CC BY 4.0 terms for the visual assets. + +MIT License + +Copyright (c) 2026 throwingogo-hub + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/LICENSE-ASSETS.md b/LICENSE-ASSETS.md new file mode 100644 index 0000000..424cf6e --- /dev/null +++ b/LICENSE-ASSETS.md @@ -0,0 +1,43 @@ +# ShadowPets asset license + +Copyright © 2026 throwingogo-hub. + +The ShadowPets visual assets are licensed under the [Creative Commons +Attribution 4.0 International license][cc-by-4.0] (CC BY 4.0). + +## Exact scope + +CC BY 4.0 applies to: + +- every image under `ShadowPets/`, including the ten static PNGs; +- every animation frame, GIF, packed sheet, and preserved source sheet; and +- `social-preview.png`, which is a composition of the same artwork. + +It does not apply to code, automation, the gallery, workflows, templates, or +documentation. Those files use the MIT License in [`LICENSE`](LICENSE). + +## What you may do + +You may use, copy, share, remix, adapt, and build upon the visual assets in +commercial or non-commercial games and projects. You must give appropriate +credit, link to the license, and indicate if you changed the assets. You may +not add legal or technical restrictions that prevent others from exercising +the rights the license grants them. + +## Copy-and-paste attribution + +Unmodified assets: + +> ShadowPets by throwingogo-hub — https://github.com/throwingogo-hub/DigitalPets — licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). + +Modified assets: + +> Based on ShadowPets by throwingogo-hub — https://github.com/throwingogo-hub/DigitalPets — modified by [YOUR NAME], licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). + +Put the credit wherever your project normally keeps asset credits: an in-game +credits screen, README, documentation page, or accompanying credits file. + +This summary does not replace the [CC BY 4.0 legal code][legal-code]. + +[cc-by-4.0]: https://creativecommons.org/licenses/by/4.0/ +[legal-code]: https://creativecommons.org/licenses/by/4.0/legalcode diff --git a/README.md b/README.md index 31c70db..fb75eed 100644 --- a/README.md +++ b/README.md @@ -1,93 +1,127 @@ -# DigitalPets 🐾 +# ShadowPets -**ShadowPets** — a collection of ten pixel-art companions. +Ten night-black pixel-art companions, ready to drop into a game: **10 static +sprites, 90 PNG frames, 30 GIFs, and 10 packed sprite sheets**. -**[Open the live animation preview →](https://throwingogo-hub.github.io/DigitalPets/)** +[**Explore the Motion Lab**](https://throwingogo-hub.github.io/DigitalPets/) · +[**Download `ShadowPets.zip`**](https://github.com/throwingogo-hub/DigitalPets/releases/latest/download/ShadowPets.zip) · +[Verify the SHA-256](https://github.com/throwingogo-hub/DigitalPets/releases/latest/download/ShadowPets.zip.sha256) · +[Read the asset license](LICENSE-ASSETS.md) -Each one is a small black creature in a dark hoodie with a blue **T** on the -chest and big, bright eyes. They're named after constellations and the things -you find in a night sky. +![ShadowPets — ten pixel-art companions](social-preview.png) - - - - - - - - - - - - - - - -
Felis
Felis
cat		Corvus
Corvus
crow		Vesper
Vesper
fox		Luna
Luna
owl		Ursa
Ursa
bear cub
Lupus
Lupus
wolf pup		Draco
Draco
dragon		Comet
Comet
bunny		Nova
Nova
axolotl		Frost
Frost
penguin
+The visual assets are licensed **CC BY 4.0**, so you may use and modify them in +commercial or non-commercial games and projects with attribution. The gallery, +scripts, automation, and documentation use the MIT License. + +> If ShadowPets earns a place in your project, consider starring the repository. +> It helps other small-game developers find the pack. + +## Use the pack in four steps + +1. Download and extract [`ShadowPets.zip`](https://github.com/throwingogo-hub/DigitalPets/releases/latest/download/ShadowPets.zip). +2. Pick a static `PetName.png`, individual PNG frames, a looping GIF, or a + packed `sheet.png`. +3. Import at **128×128** and enable nearest-neighbour / point filtering. +4. Add this line to your credits, README, or asset-credits file: -## The pack +> ShadowPets by throwingogo-hub — https://github.com/throwingogo-hub/DigitalPets — licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). -The ten static PNGs live in [`ShadowPets/`](ShadowPets/). Complete animation -sets live in [`ShadowPets/Animations/`](ShadowPets/Animations/). +If you modify the artwork, say so in the credit. Copy-ready examples and the +exact asset scope live in [`ATTRIBUTION.md`](ATTRIBUTION.md) and +[`LICENSE-ASSETS.md`](LICENSE-ASSETS.md). -- **128×128**, true pixel art at native resolution -- **Transparent**, with a crisp one-pixel white outline -- **17 colours**, one palette shared across the whole set -- **Hard edges** — no anti-aliasing, no half-transparent pixels +## What is included -They're drawn to a single scale, so the pets sit together correctly without any -resizing: Frost really is rounder than Comet, and Draco really is the big one. +| Deliverable | Count | Size | Best for | +|---|---:|---:|---| +| Static transparent PNG | 10 | 128×128 | portraits, UI, simple scenes | +| Individual animation PNG | 90 | 128×128 | engines and custom timing | +| Ping-pong GIF loop | 30 | 128×128 | prototypes, web, previews | +| Packed sprite sheet | 10 | 384×384 | one-texture engine imports | -## Animations +Every pet has `idle`, `bounce`, and `greet` motion. The visual set uses hard +alpha—no half-transparent pixels—and one shared 17-colour palette. The sprites +are drawn at a common scale, so Frost really is rounder than Comet and Draco +really is the big one. -Every pet has three looping animations: +```text +ShadowPets/ +├── Felis.png … Vesper.png +└── Animations/ + └── PetName/ + ├── idle/01.png … 03.png + ├── bounce/01.png … 03.png + ├── greet/01.png … 03.png + ├── idle.gif / bounce.gif / greet.gif + └── sheet.png +``` -- `idle` — rest, blink/dip, rise -- `bounce` — anticipation, tiny bounce, landing -- `greet` — a species-specific tail, wing, paw, ear, gill, or flipper gesture +The release ZIP contains the game-ready files above plus a per-file SHA-256 +manifest, license, attribution text, and import notes. Preserved generation +inputs remain in the repository for provenance but are intentionally excluded +from the player-facing pack. -Each loop was generated as part of that pet's own single 3×3 prompt sheet. The -same prompt structure was used for all ten pets, keeping the motion language and -rendering consistent without asking the model to redraw each frame separately. +## Meet the companions - - - - - + + + + + - - - - - + + + + +
Felis idle animation
Felis		Corvus idle animation
Corvus		Vesper idle animation
Vesper		Luna idle animation
Luna		Ursa idle animation
Ursa		Felis, a pixel-art cat
Felis
cat		Corvus, a pixel-art crow
Corvus
crow		Vesper, a pixel-art fox
Vesper
fox		Luna, a pixel-art owl
Luna
owl		Ursa, a pixel-art bear cub
Ursa
bear cub
Lupus idle animation
Lupus		Draco idle animation
Draco		Comet idle animation
Comet		Nova idle animation
Nova		Frost idle animation
Frost		Lupus, a pixel-art wolf pup
Lupus
wolf pup		Draco, a pixel-art dragon
Draco
dragon		Comet, a pixel-art bunny
Comet
bunny		Nova, a pixel-art axolotl
Nova
axolotl		Frost, a pixel-art penguin
Frost
penguin
-Each pet folder contains: +## Engine import notes -```text -PetName/ -├── idle/01.png … 03.png -├── bounce/01.png … 03.png -├── greet/01.png … 03.png -├── idle.gif / bounce.gif / greet.gif -└── sheet.png +- **Godot:** set Texture Filter to `Nearest` and define three-frame animations + from each motion folder. +- **Unity:** set Filter Mode to `Point (no filter)`, Compression to `None`, and + Pixels Per Unit consistently across all ten pets. +- **Web:** use `image-rendering: pixelated;` and scale by whole numbers such as + 2×, 3×, or 4×. + +Avoid smooth filtering and fractional scaling: both blur deliberate pixel edges. + +## Asset provenance and quality gates + +Each pet's nine animation frames came from one dedicated 3×3 source sheet. The +shared prompt structure, species-specific greeting rules, and final Luna/Ursa +anatomy corrections are documented in +[`ShadowPets/Animations/SOURCE.md`](ShadowPets/Animations/SOURCE.md). + +The asset validator enforces the public promise: exact pet/frame/GIF counts, +dimensions, hard alpha, shared palette, GIF timing, packed-sheet fidelity, +README/site links, licensing copy, social metadata, and a non-mutating +byte-for-byte rebuild. Release packaging is deterministic and verified twice. + +```bash +python3 -m pip install -r requirements-dev.txt +python3 tools/validate_assets.py --check-rebuild --check-package + +# Maintainers: create the same release files CI creates. +python3 tools/package_release.py --output dist ``` -Every individual PNG frame and animated GIF canvas is **128×128**. `sheet.png` -is the same nine frames packed into a 384×384 3×3 sprite sheet. See -[`Animations/SOURCE.md`](ShadowPets/Animations/SOURCE.md) for the shared prompt -template and generation details. +Do not run `tools/build_animations.py` against the repository casually: it is a +derivation tool for approved source sheets. CI rebuilds into a temporary +directory so validation never mutates tracked artwork. -## Using them +## Licensing -Scale by **whole numbers only** — 2×, 3×, 4× — and use nearest-neighbour -sampling. Any other factor, or smooth scaling, will blur the pixels and undo the -look. +- **Visual assets:** everything under `ShadowPets/` plus `social-preview.png` + uses [CC BY 4.0](LICENSE-ASSETS.md). +- **Code and documentation:** `index.html`, `tools/`, `.github/`, and Markdown + documentation use the [MIT License](LICENSE). -CSS: `image-rendering: pixelated;` · Unity: Filter Mode `Point (no filter)` · -Godot: Texture Filter `Nearest` +The repository URL remains `DigitalPets` so existing links, clones, and Pages +deployments keep working; the collection's public-facing name is **ShadowPets**. diff --git a/index.html b/index.html index d13539a..d424a50 100644 --- a/index.html +++ b/index.html @@ -3,8 +3,24 @@ - + + + + + + + + + + + + + + + + + ShadowPets Motion Lab