Figura Curios Bridge

# Figura Curios Bridge

> **⚠ About this mod**
> This mod was developed with the help of **Claude**, an AI made by Anthropic. A human has tested it in-game and checked that it works, but please keep this in mind.
> If you are not comfortable using AI-made mods, please do not use this mod.

**Figura Curios Bridge** lets [Figura](https://www.curseforge.com/minecraft/mc-mods/figura) avatar scripts control how [Curios](https://www.curseforge.com/minecraft/mc-mods/curios) items are rendered on the player.

Figura can't normally touch Curios items, because Curios draws them on its own. This often makes them look wrong on custom avatars: goggles sinking into hair, rings floating off the hand, and so on. This mod adds a small Lua API, so your avatar can **hide**, **move**, **rotate** or **scale** any Curios item to fit its model.

## Features
- New Lua global `curios` for Figura avatars
- Hide Curios items, or move / rotate / scale them
- Target a specific item, a whole slot, one slot index, or everything
- Transforms can follow a body part (head, body, arms, legs)
- Read what Curios items a player is wearing (`curios:getItems()`)
- Client-side only, no server install needed

## Requirements
- Minecraft **1.21.1** / NeoForge
- **Figura** 0.1.6 or later (below 0.2)
- **Curios** 9.5 or later (optional: without it, the API is still there but does nothing)

> **Note:** Effects are only visible to players who have this mod installed.
> Players without it see Curios items as usual, and nothing breaks.

## Lua API
Call these with a colon: `curios:setVisible(...)`.

**Keys** (the first match is used):
`"head#0"` (slot#index) → `"create:goggles"` (item id) → `"head"` (slot name) → `"*"` (everything)

| Function | Description |
|---|---|
| `getVersion()` | Version of this mod |
| `isAvailable()` | Whether Curios is installed |
| `isHooked()` | Whether the Curios rendering hook is active |
| `getItems()` | List of worn Curios items: `{slot, index, id, count, cosmetic, rendered}` |
| `setVisible(key, bool)` | Show / hide |
| `setPart(key, part)` | Body part to follow: `none` (default), `head`, `body`, `left_arm`, `right_arm`, `left_leg`, `right_leg` |
| `setPos(key, vec)` | Offset in pixels (same axes as Blockbench) |
| `setRot(key, vec)` | Rotation in degrees (same axes as Blockbench) |
| `setScale(key, vec)` | Scale (1 = unchanged) |
| `setPivot(key, vec)` | Pivot for rotation / scale, in pixels from the part's pivot |
| `reset(key)` / `resetAll()` | Remove settings |

Setters return `curios`, so calls can be chained.

## Examples

**Basic setup:** always check first, so your avatar still works for players without this mod.
```lua
if curios and curios:isAvailable() then
  -- your settings here
end
```

**Hide items**
```lua
curios:setVisible("create:goggles", false)   -- one item
curios:setVisible("ring", false)             -- a whole slot
curios:setVisible("ring#1", false)           -- only the 2nd ring
curios:setVisible("*", false)                -- everything
```

**Move / scale to fit your model**
```lua
local G = "create:goggles"
curios:setPos(G, vec(0, 1, -0.5))        -- 1px up, 0.5px forward
curios:setScale(G, vec(1.2, 1.2, 1.2))
```

**Follow a body part**
```lua
local N = "necklace"
curios:setPart(N, "body")
curios:setPivot(N, vec(0, -2, 0))
curios:setRot(N, vec(10, 0, 0))
```

**React to what the player is wearing**
```lua
local wait = 0
events.TICK:register(function()
  wait = wait - 1
  if wait > 0 then return end
  wait = 10   -- check every 0.5 seconds
  local goggles = false
  for _, it in ipairs(curios:getItems()) do
    if it.id == "create:goggles" and (it.rendered or it.cosmetic) then goggles = true end
  end
  -- e.g. change your avatar here
end)
```

**Animate (safe to call every frame)**
```lua
events.RENDER:register(function(delta)
  local t = world.getTime(delta)
  curios:setRot("head", vec(0, 0, math.sin(t / 10) * 5))
end)
```

## Safety
- Follows Figura's **trust settings**: nothing changes unless the viewer allows *Vanilla Model Edit* for that avatar
- Follows Figura's **panic key** and stops when the avatar's script errors
- Runs no Lua while rendering, so it doesn't use the avatar's instruction limit
- If a Curios update breaks the hook, the game keeps running. You get a chat warning, and items render normally.

## Tested with
- Figura 0.1.6
- Curios 9.5.1 – 9.5.11

Other versions may work. Untested versions are noted in the log.

## License
MIT

---