public PixelAvatar(byte key, PixelAvatarDesign design = PixelAvatarDesign.Black, PixelAvatarAnimation animation = PixelAvatarAnimation.Idle)

Initializes a new instance of this class.

Parameters

key

The key the sprite artwork is scrambled with. The library ships the sheet obfuscated and does not carry the key, so the application supplies it here; the first avatar constructed is what decodes the artwork for all of them.

public PixelAvatarDesign DesignValue

Gets the design currently used by the component.

public PixelAvatarPalette Palette

Gets the palette currently used by the component.

public PixelAvatarAnimation CurrentAnimation

Gets the animation currently playing. While auto-idling this is whichever resting pose is showing, not AutoIdle.

public bool IsAutoIdling

Gets whether the avatar is drifting between resting poses on its own, which AutoIdle turns on and any other Play turns off.

public bool IsAsleep

Gets whether the avatar is asleep, which for an auto-idling one happens on its own after SleepAfter of resting.

public int CurrentFrame

Gets the index of the frame currently shown.

public int RenderedWidth

Gets the rendered width of the avatar, in CSS pixels.

public int RenderedHeight

Gets the rendered height of the avatar, in CSS pixels.

public int PixelSizeValue { get ; set ; }

Gets or sets the size, in CSS pixels, of a single sprite pixel.

public PixelAvatarFacing FacingValue { get ; set ; }

Gets or sets the direction the avatar faces.

public bool IsPaused { get ; set ; }

Gets or sets whether playback is paused.

public PixelAvatar RestDelay(int minMs, int maxMs)

Overrides how long the resting poses hold their first frame before playing their cycle, in milliseconds. The actual hold is picked uniformly from the range every time. Pass zero for both to go back to each animation's own timing.

public PixelAvatar SleepAfter(int milliseconds)

Sets how long an auto-idling avatar rests before falling asleep, in milliseconds. The value is jittered on use. Pass zero to keep it awake indefinitely. Only AutoIdle sleeps on its own; playing an animation directly never does.

public PixelAvatar Wake()

Restarts the countdown to SleepAfter and, if the avatar is currently asleep, wakes it with a stretch and a startle before handing it back to whatever it was doing - which for an auto-idling avatar means drifting between resting poses again.

public PixelAvatar SetDesign(PixelAvatarDesign design)

Sets the design (and therefore the palette) of the component.

public PixelAvatar SetPalette(PixelAvatarPalette palette)

Sets a custom palette, whose colors map to palette indices 1..N of the sprite data.

public PixelAvatar SetShades(Color highlight, Color baseColor, Color shadow, Color background = null, string name = "Custom")

Sets a custom palette built from the artwork's three shading levels, the way the single-hue built-in designs are built.

public PixelAvatar SetColor(byte index, Color color)

Recolors a single palette index. This only rewrites that index's CSS variable, so it is cheap enough to drive from a color picker's input event.

public PixelAvatar PixelSize(int pixelSize)

Sets the size, in CSS pixels, of a single sprite pixel. The rendered avatar ends up PixelAvatarSprites.FrameWidth * pixelSize wide.

public PixelAvatar Facing(PixelAvatarFacing facing)

Sets the direction the avatar faces, mirroring the artwork when facing left. The change is instant; use Turn to animate it.

public PixelAvatar Turn(PixelAvatarFacing facing, int durationMs = DefaultTurnDurationMs)

Changes the direction the avatar faces by pivoting it about its vertical axis, so it reads as the sprite turning around rather than its pixels swapping sides. Facing the direction it already faces does nothing.

public PixelAvatar TurnAround(int durationMs = DefaultTurnDurationMs)

Pivots the avatar to face the other way. See Turn.

public PixelAvatar Outline(bool value = true)

Sets whether the sprite is drawn with a hairline halo in the theme's contrasting color. It is on by default because several palettes are pure white and several are near-black, so without it those designs disappear against one theme or the other. Turn it off when the avatar sits on a background you control and you want the artwork's colors untouched.

public PixelAvatar OutlineColor(string color)

Overrides the color of the halo drawn by Outline, which defaults to a translucent black in light mode and a translucent white in dark mode.

public PixelAvatar Speed(double speed)

Multiplies the playback speed of every animation. Values above 1 play faster.

public PixelAvatar Play(PixelAvatarAnimation animation)

Plays an animation from its first frame. Animations that do not loop hand over to a follow-up animation when they finish (see Next).

public PixelAvatar Pause()

Pauses playback on the current frame.

public PixelAvatar Resume()

Resumes playback from the current frame.

public PixelAvatar GoToFrame(int frame)

Shows a specific frame of the current animation without changing playback state.

public PixelAvatar OnAnimationFinished(Action<PixelAvatar, PixelAvatarAnimation> onAnimationFinished, bool clearPrevious = true)

Registers a callback invoked when a non-looping animation reaches its last frame, just before its follow-up animation takes over. Calling Play from the callback suppresses that hand-over.

public PixelAvatar OnAnimationStarted(Action<PixelAvatar, PixelAvatarAnimation> onAnimationStarted, bool clearPrevious = true)

Registers a callback invoked whenever a new animation starts playing.

public PixelAvatarAttachment AttachTo(IComponent target, PixelAvatarAnchor anchor = PixelAvatarAnchor.TopLeft)

Wraps target so that this avatar is anchored to one of its edges. The returned component renders the target as usual, with the avatar perched next to it. A Modal target is not wrapped - see IsAdopted.

public Button AsButton()

Wraps the avatar in a Button that has no background, border, padding or minimum size, so it hugs the avatar exactly instead of the button's usual chrome. The avatar becomes the button's content via ReplaceContent - the cat itself is the clickable surface - and the button's size tracks RenderedWidth / RenderedHeight, so it stays a perfect fit if PixelSize later changes. This claims the same pixel-size tracking slot AttachTo uses, so an avatar already attached to another component should not also be turned into a button.

public override HTMLElement Render()

Renders the component's root HTML element.

public const int DefaultPixelSize = 4

The default size, in CSS pixels, of a single sprite pixel.

public const int DefaultTurnDurationMs = 320

The default length, in milliseconds, of a Turn.

public const int DefaultSleepAfterMs = 16000

How long an auto-idling avatar rests before falling asleep, in milliseconds. Jittered on use, so the cat does not nod off on a stopwatch.

public PixelAvatarAttachment(IComponent target, PixelAvatar avatar, PixelAvatarAnchor anchor = PixelAvatarAnchor.TopLeft)

Initializes a new instance of this class.

public PixelAvatar Avatar { get; }

Gets the avatar anchored to the target.

public IComponent Target { get; }

Gets the component the avatar is anchored to.

public bool IsAdopted { get; }

Gets whether the target lends its own box to the avatar instead of being wrapped, which is what a Modal target does. An adopted target is still the component the application goes on using - Show and the rest all still apply - and this attachment's Render returns the target's own element. Adopted targets start in Overlap mode so the avatar sits outside the dialog.

public PixelAvatarCompanion Companion { get; }

Gets the behaviour driving the avatar, or null when there is none. Set when the anchor is one of the Top* ones and the target is either an OmniBox or a Modal.

public HTMLElement StylingContainer

Gets the element sizing helpers should style, which is the wrapper itself so the avatar stays anchored to the target's edges.

public bool PropagateToStackItemParent

Gets whether styling should propagate to the stack item parent.

public PixelAvatarAttachment Anchor(PixelAvatarAnchor anchor)

Moves the avatar to a different edge of the target.

public PixelAvatarAttachment Overlap(bool value = true)

Lets the avatar hang outside the wrapper's box instead of reserving room for it, so the target keeps exactly the footprint it would have on its own. Beware that an avatar in overlap mode is clipped by any ancestor that scrolls or hides its overflow. An adopted Modal starts in overlap mode, so the cat perches on the outside of the dialog; Overlap(false) moves it into a reserved band inside instead.

public PixelAvatarAttachment Offset(int x, int y)

Nudges the avatar away from its anchor by a number of CSS pixels, with positive values moving it right and down.

public HTMLElement Render()

Renders the component's root HTML element.

AutoIdle

Rest naturally: hold a pose, and every few seconds either stay put or drift to another one, wandering between standing, sitting and crouching. Starts from Idle; CurrentAnimation reports whichever pose is actually showing, and IsAutoIdling reports the behaviour.

public PixelSprite(int width, int height, byte[] pixels)

Initializes a new instance of this class from a row-major grid of palette indices.

public int Width { get; }

Gets the width of the frame, in sprite pixels.

public int Height { get; }

Gets the height of the frame, in sprite pixels.

public byte[] Pixels { get; }

Gets the palette index of every pixel, row by row (so the pixel at (x, y) lives at y * Width + x). A value of 0 means the pixel is transparent.

public bool HasEars { get ; }

Gets whether this frame has a locatable pair of ear tips.

public int EarY { get ; }

Gets the row both ear tips sit on. Only meaningful when HasEars.

public int EarLeftX { get ; }

Gets the column of the left ear tip. Only meaningful when HasEars.

public int EarRightX { get ; }

Gets the column of the right ear tip. Only meaningful when HasEars.

public int InkLeft { get ; }

Gets the left edge of the frame's non-transparent pixels.

public int InkTop { get ; }

Gets the top edge of the frame's non-transparent pixels.

public int InkWidth { get ; }

Gets the width of the frame's non-transparent pixels, or 0 if there are none.

public int InkHeight { get ; }

Gets the height of the frame's non-transparent pixels, or 0 if there are none.

public byte At(int x, int y)

Returns the palette index at the given coordinates, or 0 when out of bounds.

public PixelSpriteAnimation(PixelAvatarAnimation animation, PixelSprite[] frames, int frameDurationMs, bool loops, PixelAvatarAnimation next, int restMinMs = 0, int restMaxMs = 0)

Initializes a new instance of this class.

public PixelAvatarAnimation Animation { get; }

Gets the animation these frames belong to.

public PixelSprite[] Frames { get; }

Gets the frames, in playback order.

public int FrameDurationMs { get; }

Gets how long each frame is shown, in milliseconds.

public bool Loops { get; }

Gets whether playback restarts from the first frame after the last one.

public PixelAvatarAnimation Next { get; }

Gets the animation that takes over once this one finishes. Only meaningful when Loops is false.

public int RestMinMs { get; }

Gets the shortest time this animation holds its first frame before playing on, in milliseconds. Zero means it cycles continuously.

public int RestMaxMs { get; }

Gets the longest such hold, in milliseconds.

public bool Rests

Gets whether this animation rests on its first frame rather than cycling continuously. The resting poses do: a cat looping three frames forever reads as fidgeting, while one that holds still and twitches every few seconds reads as resting.

public int DurationMs

Gets how long a full cycle of this animation takes, in milliseconds, not counting any Rests hold.

internal static int Jittered(int milliseconds, double fraction = DefaultJitter)

Spreads a delay by a fraction of itself, so a timing that is configured as one number still does not tick like a metronome. A cat that does everything on the beat reads as a machine.

internal const double DefaultJitter = 0.2

How far a single-valued delay is spread either side of itself, by default.

public PixelAvatarPalette(string name, Color[] colors, Color background = null, Color accent = null)

Initializes a new instance of this class from colors for palette indices 1..N.

Parameters

name

The name of the palette.

colors

Exactly PaletteSize colors.

background

The avatar background color, or null to derive one from DominantColor.

public string Name { get; }

Gets the name of the palette.

public Color[] Colors { get; }

Gets the colors of palette indices 1..N, in order.

public Color Background { get; }

Gets the background color an avatar-shaped host paints behind the sprite. Only its hue is used by BackgroundGradient, which matches how Avatar colors itself.

public Color Accent { get; }

Gets the highlight painted on the ear tips, or null when the design has none. It is not a palette index: it is drawn as an extra half-size pixel on top of each ear tip, so a design can carry a spot of color the shared artwork has no cell for.

public Color ColorAt(byte index)

Returns the color for a palette index, or null for the transparent index 0 and for indices this palette does not define.

public string CssAt(byte index)

Returns the CSS color for a palette index, or an empty string for the transparent index 0 and for indices this palette does not define.

public string BackgroundGradient()

Returns the CSS background for this palette, built from Background by the same GradientForHue the regular avatar uses, so a pixel-art badge and an initials avatar look like they came out of the same set.

public Color DominantColor()

Returns the color that covers the most of the sprite, weighing each index by PixelCounts and adding up indices that share a color. Used to pick a background when one is not given.

public PixelAvatarPalette WithColor(byte index, Color color)

Returns a copy of this palette with one index recolored.

public PixelAvatarPalette WithBackground(Color background)

Returns a copy of this palette with a different avatar background color. This is how a custom palette picks the background its badge sits on; pass null to go back to one derived from the coat.

public PixelAvatarPalette WithName(string name)

Returns a copy of this palette under a different name.

public PixelAvatarPalette WithAccent(Color accent)

Returns a copy of this palette with a different ear-tip Accent. Pass null to drop it.

public override string ToString()

Returns the palette as a comma-separated list of CSS colors.

public string ToCode()

Returns C# source that reconstructs this palette, for pasting into an application.

public static PixelAvatarPalette FromColors(string name, Color background, params Color[] colors)

Builds a palette from every color of the sprite.

Parameters

name

The name of the palette.

background

The avatar background color, or null to derive one from the coat.

colors

Exactly PaletteSize colors, for palette indices 1..N.

Exceptions

ArgumentException

Thrown when the wrong number of colors is given.

public static PixelAvatarPalette FromShades(string name, Color background, Color highlight, Color baseColor, Color shadow, Color accent = null)

Builds a full palette from just the artwork's three shading levels, the way the single-hue built-in designs are built. Every palette index is filled in according to ShadeOf.

Parameters

name

The name of the palette.

background

The avatar background color, or null to derive one from the coat.

public PixelAvatar Avatar

Gets the avatar shown in the badge.

public AvatarSize SizeValue { get ; set ; }

Gets or sets the size preset of the badge.

public PixelAvatarBadge Size(AvatarSize size)

Sets the size of the badge, matching the Avatar presets.

public PixelAvatarBadge SetDesign(PixelAvatarDesign design)

Sets the design of the cat in the badge. The background follows the new palette unless Background has pinned one.

public PixelAvatarBadge SetPalette(PixelAvatarPalette palette)

Sets the palette of the cat in the badge. The background follows the new palette unless Background has pinned one.

public PixelAvatarBadge Background(string background)

Pins the CSS background of the badge instead of taking the palette's. Pass null to go back to the palette's.

public override HTMLElement Render()

Renders the component's root HTML element.

internal PixelAvatarCompanion(OmniBox omniBox, PixelAvatar avatar, HTMLElement host, PixelAvatarAnchor anchor)

Parameters

omniBox

The box the cat reacts to, or null when there is none - a companion without one only roams, since there is nothing to be typed into and no caret to walk to.

public PixelAvatar Avatar

Gets the avatar this companion drives.

public bool IsAsleep

Gets whether the cat is currently asleep.

public PixelAvatarCompanion IdleDelay(int minMs, int maxMs)

Sets the range a spontaneous animation is scheduled within. Both bounds are clamped to at least DefaultMinIdleMs so the cat never becomes a distraction. The actual delay is drawn uniformly from the range every time.

public PixelAvatarCompanion RestDelay(int minMs, int maxMs)

Sets how long the resting poses hold before the cat shifts to another one. See RestDelay; passing zero for both restores the built-in timing.

public PixelAvatarCompanion CursorDelay(int milliseconds)

Sets how long the cat waits after your last keystroke before padding over to the text caret. Pass zero to leave the caret alone entirely. Ignored by a companion with no box to watch.

public PixelAvatarCompanion SleepAfter(int milliseconds)

Sets how long the box has to stay untouched before the cat falls asleep. Pass zero to keep it awake indefinitely.

public PixelAvatarCompanion WalkSpeed(int pixelsPerSecond)

Sets how fast the cat walks, in CSS pixels per second.

public PixelAvatarCompanion WakeUp()

Wakes the cat if it is asleep and restarts the sleep countdown.

public PixelAvatarCompanion Fidget()

Plays a spontaneous animation right now, as if the timer had fired.

public PixelAvatarCompanion FollowCursor()

Walks the cat over to the text caret right now, as if the countdown had elapsed.

public const int DefaultMinIdleMs = 5000

Shortest gap between spontaneous animations, in milliseconds.

public const int DefaultMaxIdleMs = 14000

Longest gap between spontaneous animations, in milliseconds.

public const int DefaultCursorDelayMs = 10000

How long the cat waits after you stop typing before walking to the caret, in milliseconds.

public const int DefaultWalkSpeedPxPerSecond = 55

Walking speed, in CSS pixels per second.

public const int DefaultSleepAfterMs = PixelAvatar.DefaultSleepAfterMs

How long the box has to stay untouched before the cat sleeps, in milliseconds. Sleeping is the avatar's own doing, so this is just DefaultSleepAfterMs.