Accessory Editor — Manual

Chatty's redesigned avatars are more 3D-like, so every accessory needs to be re-positioned. This editor lets you do it visually, save your changes automatically, and propagate one good placement to many similar accessories or many avatars in one click.

1. Quick start

Workflow:

1. Open the editor and sign in with the username and password (or contributor code) you were given.
2. Pick an avatar in the left rail — scroll, or just start typing its number or its name in the filter box (see §3). Pick an accessory in the right rail (Hats / Eyes / Mouth / Neck / Body tabs), or type its name to find it across every category at once.
3. Position the first hat (or eye, or mouth) so it looks as close to the 2D original — shown in the small reference panel beside the stage — as you can. Drag the bbox to translate, the corner / edge handles to resize, the green dot above the box to rotate, the yellow squares to skew.

   

4. Press the Propagate button and pick All hats (or All accessories):

   

   The relative offsets between accessories on the OLD 2D avatar are preserved and shifted onto your new placement. Most accessories land correctly automatically. Then click through them quickly to spot-check and tweak the few that look off.

2. The layout

• Header (top): project name, breadcrumb, the action toolbar (icon buttons grouped by function — see §5), the ◄ ► category arrows, the "looks done" pill (only shown when every wizard anchor is placed), save status, the help popover (? button), the Review link (approvers only — see §10), 📖 Manual link, back to gallery.
• Left rail: avatar list with thumbnails (each tile shows #number · name) + a filter input. Type a number or part of a name to jump (see §3). A small green dot next to an avatar means it has saved edits.
• Stage (center): 480×480 preview with the avatar + accessory rendered. Manipulation handles overlay the accessory's bounding box.
• Reference panel: 200×200 view of the OLD 2D combo at its original baked position — your visual target.
• Right rail: category tabs (Hats / Eyes / Mouth / Neck / Body / Bottom) + an accessory list, plus a filter box that searches by number or name across every category at once (see §3). Greyed-out entries with "(no draft pos)" are accessories that have no production placement — see §12.
• Bottom toolbar: the "Editing Avatar #N · acc" label and the eight numeric x/y/w/h/r/sx/sy/z fields. (Action buttons live in the header now — see §5.)

  

3. Finding things fast — search by name

Both rails have a filter box at the top. You no longer have to remember numbers — type a name and the list narrows as you type.

Avatars — by number or name

• Type a number — 30 matches #30, #300, #301… — or part of a name (dragon, cat, phoenix).
• Matching is case-insensitive and works on any part of the name.
• Clear the box to see the whole list again. The state filter (⚫/🟡/🟢/✓) still applies on top of the name filter.

Accessories — one search across every category

• The accessory filter is cross-category: it no longer limits you to the open tab. Type crown, glasses, heart and you'll see hits from Hats, Eyes, Mouth, Neck, Body and Bottom together.
• Results are grouped under a category header (EYES · 3, HATS · 5, …) so you know where each match lives. The tab you're currently on is shown first.
• Clicking a result jumps straight to it and switches to its category — no need to find the right tab yourself.
• You can still search by number here too — 5 matches h5, h15, h50…

4. Manipulating the accessory

The dashed bounding box shows the accessory's rectangle. Around it are several handles, each with its own job:

Numeric inputs at the bottom (X / Y / W / H / Rotation / Skew X / Skew Y / Z) let you type exact values. Enter commits. Each numeric edit becomes a single undo entry, even if you typed multiple keystrokes.

5. Toolbar — every button explained

The action toolbar lives in the header, grouped by function. Every icon has a tooltip on hover (including its hotkey, when there is one). Press ? to open the cheatsheet popover that lists every icon's meaning at a glance.

6. Keyboard shortcuts

The hotkeys are split by hand and purpose: WASD triggers common toolbar actions, arrows handle navigation, brackets handle rotation, and R resets. The right hand stays on the mouse for positioning while the left hand drives the editor.

Action keys — WASD

Editing

Pixel-precise nudging is easier through the numeric X / Y fields in the bottom toolbar — type the new value and press Enter. Each numeric edit is one undo entry.

Navigation — arrows

The ↑ / ↓ shortcut is great for spot-checking how one accessory sits across many avatars: pick h1 on avatar 1, then hold ↓ to flip through 2, 3, 4… while keeping the same hat selected.

Other

7. Propagation — saving hours of work

Propagation is what makes the editor practical. After you've placed one accessory carefully, you can roll that placement out to many others, preserving the differences each accessory had in the original 2D layout.

Within this avatar

Place the first hat well. Then click ⇅ Propagate… and pick All hats on this avatar. The editor takes the relative offsets between every other hat and the anchor hat in the OLD 2D map, then applies those same offsets to your new anchor position. Result: every hat lands somewhere sensible automatically. Same for eyes and mouths.

Skew, Z, and rotation are carried as relative offsets too — so an accessory that was tilted in the old map (e.g. the rainbow scarf c54 at -30°) keeps its tilt after propagation.

Across avatars — same accessory

Place an accessory (e.g. c36 — one with no draft position) on one avatar. Then propagate across avatars: pick a reference accessory (e.g. c1) that's already positioned on every other avatar, and the editor places c36 on each one at that avatar's c1 position + the offset between c36 and c1 you set here. Effectively this teaches the editor where c36 goes by comparing to one anchor we trust.

The two checkboxes

• Skip accessories I've already manually edited — protects your hand-tuned placements from being overwritten by this propagation. Default ON.
• Reset all targets to draft first — drops every saved override on the targets in scope before applying. Use this when previous propagations from different anchors have stacked weird quirks (e.g. unintended skew from one anchor that's now polluting all targets).

8. Warp / perspective

Some accessories need to follow the avatar's gaze or head angle — not just rotate, but perspective-distort. The Warp feature solves this.

1. Click ◇ Warp. The button highlights. The four corner handles change behavior.
2. Drag any corner anywhere — independently of the others. The accessory becomes a free quadrilateral.
3. Click ◇ Warp again to leave warp mode (corners go back to resizing).
4. Click ⌅ Reset warp to undo a warp on the current accessory.

Internally the editor solves a 4-point homography from the un-warped rectangle to your quad and emits a CSS matrix3d on the image. The result composes correctly with translate, rotate, scale and skew, so you can stack effects.

Propagation carries warp through, so one well-warped accessory's perspective copies to its targets.

9. In-app preview & the iOS renderer

The stage shows how the accessory sits in the editor. But what designers really need to know is: will it look the same inside the iOS app? Two tools answer that.

The in-app preview panel

This panel mirrors the app's compositing rules, so if an accessory is being scaled down hard or clipped, you'll see it here before it ever ships.

↗ Compare in iOS app — the renderer

Click ↗ Compare in iOS app in the preview panel. It opens the renderer in a new tab for the exact avatar + accessory you currently have on screen. This is the fastest way to confirm the iOS app build is in sync with the Editor.

• The button is enabled as soon as an avatar is selected. With no accessory picked it shows just the avatar; with one picked it shows avatar + that accessory.
• The renderer URL encodes the selection (/renderer/306,h8 = avatar 306 with hat 8), so you can copy the link and share an exact comparison with the iOS team.
• If the columns don't match, the iOS app simply hasn't shipped the newest coordinate map yet — flag it to the engineer who pushes the app build.

10. Review workflow — for approvers

Every edit a contributor makes is submitted as a proposal, not written straight to production. Approvers (admin / design / support / QA roles) see a Review link in the header with a count of how many proposals are waiting.

Open Review to see proposals grouped by contributor, with an approval rate and pending / approved / rejected counts for each.

1. Expand a contributor to lazy-load their pending proposals. Each tile renders the avatar with the proposed accessory at the submitted position.
2. Approve a placement to write it into the production coordinate map. The contributor is notified and that accessory locks for them (they can re-open & re-submit if they want to change it later).
3. Reject a placement to send it back — the contributor sees the rejection, the rejected position is reloaded for them to adjust, and they can re-submit.
4. Approving edits also unlocks more avatars for that contributor, so good work earns a wider scope automatically.

11. Save, Export, recovery

• Auto-save writes every change to Firestore (collection vipconcierge_coords, one document per avatar) ~800ms after you stop editing.
• Save now forces an immediate flush.
• Export downloads a JSON snapshot of the full map (draft + every saved override) for backup or hand-off.
• Audit log: every write request is also recorded in vipconcierge_coords_audit. If anything ever goes wrong, the script tools/recover_avatar_1.py in the repo can replay the log and restore the state from before any unwanted bulk write.

12. "No draft pos" — what it means

An accessory shown faded with (no draft pos) in the right rail has no production placement on any avatar — there's no entry for it in the historical 2D coord map.

Total: 14 accessories are in this state across hats and mouths (h16, h24, h26, c24, c25, c34, c36, c37, c40, c41, c62, c63, c64, c65). Their image files exist in static-data, but the team never assigned them coordinates.

13. Tips & gotchas

• Use the reference panel. The 200×200 preview on the left of the stage shows the OLD 2D combo at its baked position. That's your visual target — match the spirit of it on the new 3D avatar.
• Position the first accessory really carefully. The propagate feature only does as good a job as the anchor placement. Spending an extra minute on the first hat saves an hour on the rest.
• Saved overrides win over the draft. When the system changes the auto-positioned draft (rare), your hand edits are unaffected — they live in Firestore separately and layer on top.
• Cache. If a recent change isn't visible, hard-refresh (Ctrl+F5) or append ?v=anything to the URL.
• Hover any button to see a tooltip describing exactly what it does. Tooltips appear after a short pause.
• The editor only works at desktop sizes. Mobile layouts aren't supported — too many handles to fit comfortably.