Desktop Pet English

Desktop Pet (English)

中文 | English

The desktop pet is Ez’s own fullscreen layer. It is not a skin component and not an Ez layout-editor component. Changing skins, resetting the HUD, or hiding the in-game HUD will not remove it. Visibility, pack, scale, and position live in Ez config.

Full pack authoring and pet.json field reference (Chinese, recommended when building packs):

• docs/桌宠使用说明.md
• Copyable template: docs/Pets/pet.json

Enable & place

Path: Settings → Ez Gameplay → Desktop pet (off by default)

Option	Purpose
Enable desktop pet	Master toggle
Show on main menu / song select / gameplay	Per-scene checkboxes
Pet pack	Scans folders with pet.json under EzResources/Pets/
Pet scale	Sprite size

Position: hover the sprite, then Left Alt + left-drag. Do not look for it in the skin or Ez layout editors.

Gameplay clicks: normal clicks pass through the sprite so aiming is unaffected; hover animations still work.

Pack layout

EzResources/Pets/
  Default/          ← built-in (placeholder blocks when no frames)
    pet.json
  YourPack/
    pet.json
    idle/
      xxx_000.png
      xxx_001.png
    hover/
    poke/
    …

Rules of thumb:

1. One folder per action; folder name matches the clip id (star_easy is accepted for starEasy).
2. Frame filenames need a _digits suffix (prefer _000, _001, …). png / jpg are supported.
3. Missing folder or no valid frames: that action never fires; others still work.
4. Pure-black AI frames without matting: set "blendMode": "blackKey" in pet.json.

pet.json rules (summary)

action	Effect
play (default)	Jump to goto and play a clip
show	Make visible; optional goto
hide	Hide until a later show, or until leaving gameplay

Common events: hover / hoverEnd / click / gameplayEnter / combo (at) / miss (optional streak) / idle (afterSeconds).

The docs template hides on enter, shows (and plays) at combo 200, then hides again at combo 500.

Make your own pack

1. Create a folder under EzResources/Pets/ (name = pack dropdown value).
2. Add pet.json (copy the template above or Default/pet.json).
3. Add per-action folders and frame sequences.
4. Select the pack in settings; after editing files, re-enter or switch the pack name to reload.

Frame-generation prompts (character lock + storyboards):

• 咕嘎-动画帧生成.md
• Doro-动画帧生成.md

Export one folder per action; do not dump all frames in the pack root.

Live2D (optional)

• Place the pack under EzResources/Pets/<pack>/ with "renderer": "live2d".
• Cubism Core under _cubism/<platform>/ or the SDK Core/dll tree.
• Same rules as PNG; clips can activate stacked parameter expressions (smile/wave/jump). Template: pet.live2d.example.json
• Settings: optional “Live2D lip-sync to music”.
• Details: Live2D测试指南.md

FAQ

• Only coloured blocks: Default uses placeholders when frames are missing; drop PNGs into the action folders.
• Nothing visible: confirm the master toggle; default is lower-right — Alt-drag to move. It never appears in editor component lists.
• Click does nothing: gameplay clicks intentionally pass through; try song select, or rely on hover.
• Purple Live2D placeholder: usually missing Core under _cubism/<rid>/, or no model entry under live2d/.