bedrockskin

type Angle string

type AnimatedTexture struct {
	Type    AnimatedType
	Texture image.Image
}

type AnimatedTextureBytes struct {
	Type    AnimatedType
	Texture []byte // an encoded PNG or JPEG
}

type AnimatedType int

type Animation struct {
	// Name is its key in the file, e.g. "animation.player.wave".
	Name string
	// Loop is whether it starts over at the end; HoldOnLastFrame keeps the
	// last pose instead (as does not looping, once it has finished).
	Loop            bool
	HoldOnLastFrame bool
	// Length is how long it runs, in seconds: animation_length, or the last
	// keyframe's time when the file leaves it out.
	Length float64
	// contains filtered or unexported fields
}

type AnimationBytesOptions struct {
	BytesOptions

	Animation Animator // required; ErrNoAnimation without one
	FPS       int
	Frames    int
	Workers   int
}

type AnimationOptions struct {
	Options

	// Animation is what moves the model: a built-in Motion, or an Animation
	// from ParseAnimations. Required.
	Animation Animator
	// FPS is frames per second; zero means 20.
	FPS int
	// Frames is how many frames to render; zero means one loop.
	Frames int
	// Workers is how many frames are rasterized at once; zero means
	// GOMAXPROCS, one means one at a time. Frames are independent, so the
	// images are the same either way; a server already rendering on every
	// core may want 1. See docs/design-decisions.md#why-animation-frames-render-in-parallel.
	Workers int
}

type Animator interface {
	// Duration is the length of one loop, in seconds.
	Duration() float64
	// Pose is the pose t seconds in.
	Pose(t float64) Pose
}

type Armor struct {
	Helmet     image.Image
	Chestplate image.Image
	Leggings   image.Image
	Boots      image.Image
	// Elytra is the elytra's texture (textures/models/armor/elytra.png),
	// worn on the back. It takes the chestplate's slot, as in game: with
	// both set, only the elytra is worn. See docs/equipment.md#elytra.
	Elytra image.Image
}

type ArmorBytes struct {
	Helmet     []byte
	Chestplate []byte
	Leggings   []byte
	Boots      []byte
	Elytra     []byte
}

type Bone struct {
	Name     string    `json:"name"`
	Parent   string    `json:"parent,omitempty"`
	Pivot    []float64 `json:"pivot,omitempty"`
	Rotation []float64 `json:"rotation,omitempty"`
	Inflate  float64   `json:"inflate,omitempty"`
	Mirror   bool      `json:"mirror,omitempty"`
	Cubes    []Cube    `json:"cubes,omitempty"`

	// The rest of the schema, kept so a whole file can be read. Poly
	// meshes are drawn (read one with Mesh); texture meshes are parsed but
	// not drawn. See docs/geometry-format.md#everything-else-in-a-bone.
	BindPoseRotation []float64          `json:"bind_pose_rotation,omitempty"`
	Locators         map[string]Locator `json:"locators,omitempty"`
	PolyMesh         json.RawMessage    `json:"poly_mesh,omitempty"`
	TextureMeshes    json.RawMessage    `json:"texture_meshes,omitempty"`
}

type BonePose struct {
	Rotation [3]float64
	Position [3]float64
	Scale    [3]float64
	Scaled   bool
}

type BytesOptions struct {
	// Texture is an encoded PNG or JPEG. Required.
	//
	// Bedrock sends skins as raw RGBA rather than an encoded image; use
	// TextureFromRGBA for those and the Options/Render path instead.
	Texture []byte

	// Geometry is a raw geometry.json. Nil, empty, or the literal "null" a
	// Bedrock client sends for a built-in model all fall back to
	// DefaultGeometry, so a skin's field can be passed straight through.
	Geometry []byte

	// Cape is an encoded PNG or JPEG cape texture, or nil.
	Cape []byte

	// Animated holds a persona skin's animation images, encoded; see
	// Options.Animated.
	Animated []AnimatedTextureBytes
	// Armor is Options.Armor with each piece's texture encoded.
	Armor ArmorBytes
	// RightHand and LeftHand are Options' hands with the item encoded.
	RightHand HeldBytes
	LeftHand  HeldBytes

	Identifier string
	View       View
	Angle      Angle
	Parts      []string
	Camera     *Camera
	Size       int
	// Scale and HideSkin are Options' fields. With HideSkin, Texture may be
	// empty.
	Scale    Scale
	HideSkin bool
}

type Camera struct {
	// Yaw rotates the camera around the vertical axis, in degrees. 0 is
	// straight-on front; positive values swing the camera around to bring
	// more of the subject's left side into view.
	Yaw float64
	// Pitch raises the camera, in degrees. 0 is level with the subject's
	// centre; positive values look down and reveal top-facing surfaces.
	Pitch float64
	// FOV is the field of view in degrees. Zero means 35. Small values
	// (~15-20) read as flat and zoomed in; large ones (~50+) add perspective
	// distortion, which suits dramatic close framing.
	FOV float64
	// Margin is how much room to leave around the subject. Zero means 1.5.
	// 1.0 frames as tightly as possible without clipping; larger values pull
	// the camera back.
	Margin float64
}

type Cube struct {
	Origin  []float64       `json:"origin"`
	Size    []float64       `json:"size"`
	UV      json.RawMessage `json:"uv"`
	Inflate *float64        `json:"inflate,omitempty"`
	Mirror  bool            `json:"mirror,omitempty"`
	// Rotation turns the cube about Pivot, in degrees; Pivot is in model
	// space and defaults to the cube's centre. See
	// docs/geometry-format.md#rotation.
	Rotation []float64 `json:"rotation,omitempty"`
	Pivot    []float64 `json:"pivot,omitempty"`
}

type FaceUV struct {
	UV               []float64 `json:"uv"`
	UVSize           []float64 `json:"uv_size,omitempty"`
	UVRotation       float64   `json:"uv_rotation,omitempty"`
	MaterialInstance string    `json:"material_instance,omitempty"`
}

type Frames struct {
	// contains filtered or unexported fields
}

type Geometry struct {
	Identifier    string
	TextureWidth  float64
	TextureHeight float64
	Bones         []Bone

	// The visible bounds: the box, in blocks, the game uses to decide the
	// model is on screen. Zero when the file leaves them out.
	VisibleBoundsWidth  float64
	VisibleBoundsHeight float64
	VisibleBoundsOffset []float64
}

type GeometrySizeResult struct {
	Pass       bool
	Violations []GeometryViolation
}

type GeometryTree struct {
	// FormatVersion is the file's format_version, e.g. "1.12.0".
	FormatVersion string
	// contains filtered or unexported fields
}

type GeometryValue struct {
	Path  string
	Value any
}

type GeometryViolation struct {
	Bone    string
	Size    float64
	Minimum float64
}

type Held struct {
	// Item is the item's sprite, e.g. textures/items/diamond_sword.png,
	// drawn extruded and placed where the game places it, with the arm
	// held forward. Nil holds nothing; nor does geometry without the arm.
	Item image.Image
	// Flat holds it as the game holds an item that is not a tool or
	// weapon - food, materials. False holds it upright, as a sword.
	Flat bool
	// Adjust moves the item from where the game puts it, for an item that
	// placement does not suit.
	Adjust ItemAdjust
}

type HeldBytes struct {
	Item   []byte
	Flat   bool
	Adjust ItemAdjust
}

type ItemAdjust struct {
	// Offset moves the item, in model units along the model's axes, as a
	// bone's position moves a bone.
	Offset [3]float64
	// Rotation turns the item about its grip, in degrees, as a bone's
	// rotation turns a bone: a positive X tips its top forward.
	Rotation [3]float64
	// Scale resizes the item about its grip. Zero means 1.
	Scale float64
}

type ItemAnimationBytesOptions struct {
	ItemBytesOptions

	Duration float64
	FPS      int
	Frames   int
}

type ItemAnimationOptions struct {
	ItemOptions

	// Duration is how long one turn takes, in seconds. Zero means 3.
	Duration float64
	// FPS is frames per second; zero means 20.
	FPS int
	// Frames is how many frames to render; zero means one turn.
	Frames int
}

type ItemBytesOptions struct {
	Item   []byte
	Angle  Angle
	Camera *Camera
	Size   int
	Adjust ItemAdjust
}

type ItemOptions struct {
	// Item is the item's sprite, e.g. textures/items/diamond_sword.png.
	Item image.Image
	// Angle picks the camera preset: AngleFront faces the sprite, as an
	// inventory icon; AngleIso turns it to show its depth. Zero means
	// AngleFront. Ignored when Camera is set.
	Angle Angle
	// Camera overrides Angle with an explicit position.
	Camera *Camera
	// Size is the output edge length; the image is square. Zero means
	// DefaultSize.
	Size int
	// Adjust turns and resizes the item about its centre. The camera frames
	// the item whatever its size or offset, so Scale and Offset change only
	// its shape against other parts, not how big it looks.
	Adjust ItemAdjust
}

type Locator struct {
	Offset               []float64 `json:"offset"`
	Rotation             []float64 `json:"rotation,omitempty"`
	IgnoreInheritedScale bool      `json:"ignore_inherited_scale,omitempty"`
}

type Motion string

type Options struct {
	// Texture is the decoded skin image. Required. Bedrock skins are
	// normally 64x64 or 128x128, but any size works.
	Texture image.Image

	// Geometry is the skin's model, as returned by ParseGeometry. Leave it
	// nil for a skin that uses a built-in model — DefaultGeometry stands in,
	// which is what a Bedrock client would render. See DefaultGeometry for
	// why this is the common case rather than a convenience.
	Geometry []Geometry

	// Identifier picks which entry of Geometry to render when it holds more
	// than one, which is usual: a bundle typically carries a cape entry plus
	// both arm variants. It matches the identifier named in the skin's
	// resource patch, e.g. "geometry.humanoid.customSlim".
	//
	// The resource patch is the authoritative wide-vs-slim selector. The
	// login packet's ArmSize field is not: real captures show the two
	// disagreeing, with ArmSize reporting "wide" for a skin whose patch
	// names customSlim.
	//
	// Empty, or naming an entry that isn't present, falls back to the entry
	// with the most cubes. See SelectGeometry.
	Identifier string

	// Cape is an equipped cape texture, or nil.
	//
	// The cape mesh comes from a "cape" bone in Geometry, or from the
	// built-in geometry.cape when Geometry has none — which is the usual
	// case, since capes live in their own entry and never travel merged into
	// a custom skin's body. Not drawn for ViewHead or ViewAvatar, which do
	// not show one.
	Cape image.Image

	// View selects the framing: body, chest, head or avatar. Zero means
	// ViewBody. Ignored when Parts is set.
	View View

	// Angle picks the camera preset for View: straight-on or the angled
	// 3-quarter "head icon" look. Zero means the default for the chosen
	// View, which is AngleIso for ViewHead and AngleFront elsewhere.
	// Ignored when Camera is set.
	Angle Angle

	// Parts names exactly which bones to render, e.g.
	// []string{"head", "leftArm"}. Each name pulls in everything parented
	// under it, so "head" also brings a hat or hair bone. Empty means use
	// View instead.
	Parts []string

	// Camera overrides the View/Angle framing with an explicit position.
	Camera *Camera

	// Size is the output edge length in pixels; the image is always square.
	// Zero means DefaultSize.
	Size int

	// Pose moves bones from where the geometry puts them, e.g. a frame of a
	// Motion (see Motion.Pose). Nil is the rest pose.
	Pose Pose

	// Animated holds the extra textures a persona skin's animations carry -
	// the face, and animated body parts. Each draws the geometry entry made
	// for it alongside the main one; a persona skin's head lives only in its
	// face entry. See docs/geometry-format.md#persona-skins.
	Animated []AnimatedTexture

	// Armor is the armor worn over the skin. The zero value wears none.
	// See docs/equipment.md.
	Armor Armor
	// RightHand and LeftHand are the items held in each hand. The zero
	// value holds nothing. See docs/equipment.md#held-items.
	RightHand Held
	LeftHand  Held
	// Scale resizes the figure or any bone. The zero value changes
	// nothing. See docs/equipment.md#scale.
	Scale Scale
	// HideSkin draws the equipment alone - armor, elytra, held items and
	// cape - posed and framed as it would be on the skin, so any piece can
	// be rendered by itself; Parts and View pick which. Texture may then be
	// nil. ErrEmptyView or ErrNoMatchingParts means no equipment was left
	// to draw. See docs/equipment.md#equipment-on-its-own.
	HideSkin bool
}

type PartReport struct {
	// Name is the body part or overlay/geometry bone name (head, hat, cape, ...).
	Name string `json:"name"`
	// Visibility is why this part counts as rendering or not. Visible reports
	// the same thing as a bool when the distinction does not matter.
	Visibility PartVisibility `json:"visibility"`
	// OpaqueRatio is the share of the part's sampled pixels that are opaque,
	// from 0 to 1.
	OpaqueRatio float64 `json:"opaque_ratio"`
	// Pixels is how many texture pixels were sampled for this part, and
	// Transparent how many of those were see-through.
	Pixels      int `json:"pixels"`
	Transparent int `json:"transparent_pixels"`
	// FromGeometry is true when this part was resolved from real geometry
	// cube UVs rather than the standard-layout fallback.
	FromGeometry bool `json:"from_geometry"`
}

type PartVisibility int

type PolyMesh struct {
	// NormalizedUVs means UVs are 0..1 across the texture; otherwise they
	// are texture pixels against the entry's declared texture size.
	NormalizedUVs bool        `json:"normalized_uvs"`
	Positions     [][]float64 `json:"positions"`
	Normals       [][]float64 `json:"normals"`
	UVs           [][]float64 `json:"uvs"`
	// Polys is a list of polygons, each a list of [position, normal, uv]
	// index triples, or the string "tri_list" / "quad_list" for vertices
	// taken in order. Polygons resolves them.
	Polys json.RawMessage `json:"polys"`
}

type PolyVertex struct {
	Position [3]float64
	Normal   [3]float64 // zero when the corner names no usable normal
	UV       [2]float64
}

type Pose map[string]BonePose

type ResourcePatch struct {
	// Default is the identifier of the body geometry, e.g.
	// "geometry.humanoid.customSlim". Pass it as Options.Identifier.
	Default string
	// Cape is the cape geometry identifier when the patch names one, and
	// empty otherwise. Most patches name only Default.
	Cape string
}

type Scale struct {
	// Model is the figure's size in the image: 2 draws it twice as large,
	// cropping what no longer fits; 0.5 half as large. Zero means 1. The
	// camera frames the model whatever its size, so only this changes how
	// big it looks.
	Model float64
	// Parts scales bones by name, ignoring case, each about its own pivot
	// and carrying everything parented under it: the armor on it, and an
	// arm's held item. 0 hides a bone.
	Parts map[string]float64
}

type Skin struct {
	// contains filtered or unexported fields
}

type SkinOptions struct {
	// MinVisibleFraction is the share of a part's sampled pixels that must be
	// opaque for it to count as visible. Zero means DefaultMinVisibleFraction.
	MinVisibleFraction float64

	// MinGeometrySize is the world-space size a bone must reach to avoid
	// being judged too small to see. Zero means DefaultMinGeometrySize. It
	// applies only when geometry is supplied.
	MinGeometrySize float64

	// MinVisibleParts is how many of the six standard body parts must be
	// visible before the skin stops being suspicious. Zero means
	// DefaultMinVisibleParts.
	MinVisibleParts int
}

type SkinPartResult struct {
	Name        string
	Visible     bool
	Fraction    float64
	Pixels      int
	Transparent int
	FromGeo     bool // true when the part came from geometry, not the fallback layout
	Tiny        bool // true when the geometry defines the part below the minimum size
}

type SkinReport struct {
	// Verdict is the overall judgement.
	Verdict Verdict `json:"verdict"`
	// VisibleParts is how many of the standard body parts render, out of
	// TotalParts. Overlay layers fold into the part they cover and
	// accessories are ignored, so an opaque cape cannot mask an invisible
	// body.
	VisibleParts int `json:"visible_parts"`
	TotalParts   int `json:"total_parts"`
	// Parts is the per-part breakdown: the standard body parts first, in a
	// fixed order, then every other bone sorted by name.
	Parts []PartReport `json:"parts"`
}

type SkinVisibilityResult struct {
	IsInvisible    bool
	Pass           bool
	Suspicious     bool
	Parts          []SkinPartResult
	VisibleParts   int
	InvisibleParts int
}

type Verdict int

type View string

type WireAnimation struct {
	Type          AnimatedType
	Data          []byte
	Width, Height int
}

type WireSkin struct {
	// SkinData is the skin's pixels, raw non-premultiplied RGBA,
	// SkinWidth*SkinHeight*4 bytes. Required.
	SkinData              []byte
	SkinWidth, SkinHeight int

	// CapeData is the cape's pixels in the same form; empty for no cape.
	CapeData              []byte
	CapeWidth, CapeHeight int

	// Geometry is SkinGeometryData. Empty or the literal "null" - what a
	// client sends for a built-in model - draws the default model.
	Geometry []byte

	// ResourcePatch is SkinResourcePatch: it names which entry of Geometry
	// the skin uses, wide or slim among them.
	ResourcePatch []byte

	// Animations is the skin's animation list. A persona skin's face, and
	// some of its body, are textured by these.
	Animations []WireAnimation
}