rpg-actor

Give your website a little character.

A pixel-sized companion for the open web. Walk in four directions, wear nine expressions, and talk with your whole face. All through HTML attributes.

Web Component · Zero dependencies · MIT · 1.0.0

My RPG Actor character sprite — My rpg.actor sprite

walk · down · neutral

This actor has published expression sheets. Try an expression with Talking enabled.

The form works without JavaScript: Apply renders the selected pose on the server. JavaScript adds live playback. Your reduced-motion preference keeps the sprite still.

A character that travels with you

rpg.actor stores your character’s sprite and stats in your AT Protocol account, ready for compatible games and websites. This independent component displays those sheets; it does not change your account.

The Getting Emotional announcement adds optional expression and talking variants. No extra animation library required.

Start with HTML

Copy the component directory from a reviewed GitHub commit into your site’s /vendor/rpg-actor/ directory, keeping the license. Serve these ES modules from your own origin.

A walking character

<script type="module" src="/vendor/rpg-actor/index.js"></script>
<rpg-actor src="/sprites/me.png" animation="walk"
	direction="down" expression="happy" label="My character">
	<img src="/sprites/me-portrait.png" alt="My character" width="144" height="144">
</rpg-actor>

The child image is your no-JavaScript and failed-image fallback. Use a cropped portrait or your own HTML. The enhanced sprite uses a shadow root and leaves that content intact.

Expressions, then state changes

const actor = document.querySelector('rpg-actor');
actor.setAttribute('emotes', JSON.stringify({
	happy: {
		emoteSheet: '/sprites/happy.png',
		talkSheet: '/sprites/happy-talking.png'
	}
}));
actor.setAttribute('expression', 'happy');
actor.setAttribute('talking', '');
actor.setAttribute('direction', 'left');
actor.setAttribute('paused', ''); // remove to resume
actor.addEventListener('actor-change', ({ detail }) => console.log(detail));

The HTML interface

Always use the rpg.actor developer guide as the authoritative reference when integrating or updating this component. Its current sprite, emote, and API contracts take precedence over examples here.

Sprite attributes
Attribute	Values and defaults
`src`	Base sheet URL. Relative or HTTP(S). No credentials required.
`emotes`	JSON keyed by expression, with `emoteSheet` and optional `talkSheet` URLs.
`expression`	neutral (default), blink, happy, sad, angry, silly, tired, bruh, pout.
`direction`	down (default), left, right, up.
`animation`	idle (default) or walk. Walking uses the standard 0, 1, 2, 1 frame order.
`talking`	Boolean presence alternates closed and open mouth sheets.
`showcase`	Boolean presence cycles available expressions, directions, walking, idle, and talking. Each expression keeps its direction through the three poses.
`showcase-duration`	Milliseconds per pose, default 2400; 150–60000, rounded up to the next frame. Invalid values use 2400; values below 150 become 150. For example: `showcase showcase-duration="3000"`.
`paused`	Boolean presence freezes playback. The built-in pause button reflects this attribute.
`columns`, `rows`	Base grid, default 3 × 4; 1–16. Emotes always use 3 × 4.
`interval`	Milliseconds per frame, default 150; clamped to a minimum of 50, maximum accepted value 2000.
`frame`	Optional zero-based column override. Remove for automatic playback.
`label`	Accessible image name, default “RPG character”.

Boolean attributes use presence: paused="false" still pauses. Unknown enum values use defaults. Invalid numbers use defaults; zero dimensions become one. Remove showcase before taking manual control.

Events, styling, and limits

actor-change reports { animation, direction, expression, talking, paused } after attribute changes and showcase steps. actor-load reports { src } for loaded sheets; actor-error reports { reason, src } for malformed JSON or failed images. Events bubble, cross shadow boundaries, and are not cancelable. No incoming custom events or custom public methods.

Set --rpg-actor-size: 192px to resize. Style ::part(sprite) and ::part(controls). The default slot holds fallback HTML. Images retain crisp pixels.

Missing or failed variants use the base sprite. Failed base images expose your fallback. Only visited sheets load; images are reused within each instance. Hidden documents and disconnected elements stop playback. Reduced motion disables walking, talking, and showcase progression while preserving manual pose selection.

Read an actor’s actor.rpg.sprite/self record on your server and resolve its blob references to image URLs. This component accepts URLs, not raw blob objects, and makes no authenticated API requests. Host the sheets yourself or permit their origin in your image CSP. Permit the component’s shadow styles in your style policy. Code is MIT; sprite artwork retains its owner’s license.

For npm, pnpm, or Yarn, install the vendored local directory and import @jessehattabaugh/rpg-actor from your browser entry. The /element export provides RpgActor for manual registration. Do not import browser classes during server rendering. See the README for commands and the official sprite specification for record details.