LOLCodexPet

Build animated Codex desktop pets from Khada League of Legends and Teamfight Tactics 3D models. This repository contains a reusable Codex skill that finds or accepts GLB assets, selects motion-rich keyframes, renders transparent sprites in Blender, assembles the current Codex pet atlas, validates the result, and installs the finished pet. Image generation is not used by default.

LOLCodexPet was created under Riot Games' "Legal Jibber Jabber" policy using assets owned by Riot Games. Riot Games does not endorse or sponsor this project.

What the skill does

• accepts local GLB/GLTF files, a modelviewer.lol URL from Khada, or a tactician name;
• inventories the real animation clips before choosing state mappings;
• renders transparent high-resolution frames with consistent camera, lighting, scale, and grounding;
• inspects dense motion timelines where needed, so loops show real phase changes such as alternating footsteps;
• builds and validates the Codex v2 spritesheet, including all nine animation states and sixteen look directions;
• creates QA evidence, packages the pet, and optionally installs it locally;
• keeps source models, full renders, tool downloads, and installable Riot-derived binaries out of Git by default.

The main workflow is:

discover or accept model -> inspect actions -> select motion phases -> render in Blender
-> audit frames -> assemble and validate atlas -> preview -> package/install

Gwen example

examples/Gwen is an example built with this skill. It records the source provenance, render configuration, state/action mapping, compact QA results, and package metadata for a Codex v2 Gwen pet.

Idle	Running right	Waving
Jumping	Failed	Review

These small documentation screenshots are Riot-derived fan content and are not licensed under Apache-2.0. The source GLB, complete atlas, previews, and ready-to-install package are intentionally not distributed in this repository. See Third-party assets.

Install the skill

Requirements

• Codex with the current hatch-pet skill available. This skill uses its atlas contract, deterministic assembly, validation, preview, packaging, and installation utilities, but does not use its image-generation path.
• Python 3.10 or newer. Pillow is required by the image and QA helpers; certifi is optional.
• Blender. On Windows x64, the skill can download and verify an official portable build into the target workspace's ignored tools/blender-portable/ directory. On other platforms, provide a compatible Blender on PATH.

Copy into your Codex skills directory

Clone this repository, then copy or symlink skills/build-lol-3d-pet into your Codex skills directory.

Windows PowerShell:

git clone https://github.com/Xiaochr/LOLCodexPet.git
Set-Location LOLCodexPet
$codexRoot = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $HOME ".codex" }
$skillsRoot = Join-Path $codexRoot "skills"
New-Item -ItemType Directory -Force -Path $skillsRoot | Out-Null
Copy-Item -Recurse -Force ".\skills\build-lol-3d-pet" $skillsRoot

macOS or Linux:

git clone https://github.com/Xiaochr/LOLCodexPet.git
cd LOLCodexPet
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R skills/build-lol-3d-pet "${CODEX_HOME:-$HOME/.codex}/skills/"

Reload Codex after copying. The installed entry point should be:

<CODEX_HOME>/skills/build-lol-3d-pet/SKILL.md

For development, symlink or directory-junction the skill folder instead of copying it so local updates take effect after a Codex reload.

Use the skill

Ask Codex to use $build-lol-3d-pet. The skill supports three input levels:

1. Local files and explicit mapping

   Use $build-lol-3d-pet to build MyPet from the GLB files in ./source.
   Map idle to Idle, running-right/running-left/running to Run,
   failed to Death, and review to Celebrate.
   

2. Name or URL with explicit mapping

   Use $build-lol-3d-pet to build Gwen from
   https://modelviewer.lol/model-viewer?group=tft&id=68001&lang=zh-CN.
   Use Idle_Base for idle, Run for the running states, and Death for failed.
   

3. Name only, with automatic discovery and motion selection

   Use $build-lol-3d-pet to find the TFT tactician Gwen, choose suitable
   animations for every Codex pet state, build it, validate it, and install it.
   

Explicit user mappings always take priority. Automatic selection still requires animation inventory, dense inspection of ambiguous motion, and visual QA before packaging.

Repository layout

LOLCodexPet/
|-- skills/build-lol-3d-pet/    # Shareable Codex skill and reusable scripts
|-- examples/Gwen/              # Reproducible public example metadata and showcase
|-- tools/                      # Local Blender/FFmpeg caches; ignored by Git
|-- LICENSE                     # Apache-2.0 for repository-authored material
|-- NOTICE
|-- THIRD_PARTY_ASSETS.md
+-- README.md

The local Gwen directory may additionally contain ignored build inputs and outputs:

examples/Gwen/
|-- source/model.glb            # Third-party source; local only
|-- run/                        # Regenerable frames, previews, and detailed QA
|-- package/spritesheet.webp    # Installable Riot-derived atlas; local only
|-- pet-render-config.json      # Tracked reproducible configuration
+-- showcase/                   # Six small documentation frames

Reusable behavior belongs in the skill. Character-specific mappings, source manifests, and compact review evidence belong in an example.

Efficient workflow

The optimized workflow validates configuration and runs Blender in planning mode before production. It uses short overview timelines, escalates to dense inspection only for ambiguous or periodic motion, groups states by source model, renders the sixteen look directions in one import, supports fingerprinted --resume, and runs independent post-render checks concurrently where safe. Production Blender jobs remain serialized to avoid GPU/CPU contention. See efficient-workflow.md.

License and third-party assets

Repository-authored skill instructions, Python/Blender scripts, documentation, configuration, and QA logic are licensed under the Apache License 2.0. Riot models, textures, animations, character likenesses, trademarks, and derived renders are not covered by that license.

Before publishing any Riot-derived output, read THIRD_PARTY_ASSETS.md, Riot's current Legal Jibber Jabber and Terms of Service, and modelviewer.lol's Terms of Use. This repository's default is local generation, not redistribution of source models or installable character binaries.