Documentation
¶
Overview ¶
Package act provides functionality for reading and writing ACT (Animation) files used by Ragnarok Online.
ACT files contain sprite animations composed of actions, frames, and layers. This package supports reading ACT versions 2.0 through 2.5.
Example usage:
data, err := os.ReadFile("sprite.act")
if err != nil {
log.Fatal(err)
}
anim, err := act.Decode(data)
if err != nil {
log.Fatal(err)
}
// Get information
fmt.Printf("Actions: %d\n", len(anim.Actions))
fmt.Printf("First action frames: %d\n", len(anim.Actions[0].Frames))
Index ¶
- type Action
- type Anchor
- type Animation
- func (a *Animation) ActionCount() int
- func (a *Animation) ExportSpriteSheet(w io.Writer, sprite *spr.Sprite, actionIndex int, layout SpriteSheetLayout, ...) error
- func (a *Animation) GenerateSpriteSheet(sprite *spr.Sprite, actionIndex int, layout SpriteSheetLayout, padding int) (image.Image, error)
- func (a *Animation) Render(sprite *spr.Sprite, actionIndex, frameIndex int) (image.Image, error)
- type Color
- type Frame
- type Header
- type Layer
- type SpriteSheetLayout
- type SpriteType
- type Version
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Action ¶
type Action struct {
// AnimationSpeed controls playback speed (multiply by 25ms for frame interval)
// Example: speed=4.0 means 100ms per frame (4 * 25ms)
AnimationSpeed float32
// Frames contains all animation frames for this action
Frames []Frame
}
Action represents a single animation sequence (e.g., walk, attack, idle).
An action is composed of multiple frames played in sequence.
type Anchor ¶
type Anchor struct {
// Unknown field (purpose unclear, usually zeros)
Unknown [4]byte
// OffsetX is the horizontal position of the anchor point
OffsetX int32
// OffsetY is the vertical position of the anchor point
OffsetY int32
// Other field (purpose unclear)
Other int32
}
Anchor represents an attachment point for aligning sprites.
Anchors are used to attach weapon sprites, effects, or other sprites to specific points on a character (v2.3+ only).
type Animation ¶
type Animation struct {
// Header contains version and action count information
Header Header
// Actions is the list of animation sequences (e.g., idle, walk, attack)
Actions []Action
// SoundFiles lists sound effect filenames (v2.1+ only)
SoundFiles []string
}
Animation represents a complete ACT animation file.
An ACT file defines animations for sprites, organized as a collection of actions. Each action contains multiple frames, and each frame has layers of sprites.
func Decode ¶
Decode decodes an ACT file from raw bytes.
The decoding process:
- Reads and validates the header
- Reads all actions, frames, and layers
- Reads sound files (v2.1+)
- Reads animation speeds (v2.2+)
Returns an error if the file is corrupted or has an unsupported version.
Example:
data, _ := os.ReadFile("sprite.act")
anim, err := act.Decode(data)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%d actions with %d frames each\n",
anim.ActionCount(), len(anim.Actions[0].Frames))
func (*Animation) ActionCount ¶
ActionCount returns the number of actions (animation sequences) in this file.
Typical RO sprites have 8-64 actions for different character poses and animations.
func (*Animation) ExportSpriteSheet ¶
func (a *Animation) ExportSpriteSheet(w io.Writer, sprite *spr.Sprite, actionIndex int, layout SpriteSheetLayout, padding int) error
ExportSpriteSheet generates and saves a sprite sheet to a writer
This is a convenience method that combines GenerateSpriteSheet and PNG encoding.
Example:
f, _ := os.Create("spritesheet.png")
defer f.Close()
err := anim.ExportSpriteSheet(f, sprite, 0, act.LayoutGrid, 2)
func (*Animation) GenerateSpriteSheet ¶
func (a *Animation) GenerateSpriteSheet(sprite *spr.Sprite, actionIndex int, layout SpriteSheetLayout, padding int) (image.Image, error)
GenerateSpriteSheet creates a sprite sheet image containing all frames of an action
Parameters:
- sprite: The SPR sprite file containing image frames
- actionIndex: Which action/animation to render (0-based)
- layout: How to arrange frames (horizontal, vertical, or grid)
- padding: Pixels of spacing between frames
Returns an image containing all frames arranged according to layout.
Example:
sheet, err := anim.GenerateSpriteSheet(sprite, 0, act.LayoutGrid, 2)
if err != nil {
log.Fatal(err)
}
// Save sprite sheet
f, _ := os.Create("spritesheet.png")
png.Encode(f, sheet)
func (*Animation) Render ¶
Render renders a specific animation frame by compositing all layers.
This method takes a sprite (SPR file) and renders a frame from a specific action, applying all layer transformations (position, scale, mirror, color tint).
Parameters:
- sprite: The SPR sprite file containing image frames
- actionIndex: Which action/animation to render (0-based)
- frameIndex: Which frame within that action (0-based)
Returns the composed image with all layers rendered, or an error if indices are invalid.
Example:
// Load SPR and ACT files
sprData, _ := os.ReadFile("sprite.spr")
actData, _ := os.ReadFile("sprite.act")
sprite, _ := spr.Decode(sprData)
anim, _ := act.Decode(actData)
// Render first frame of idle action
img, err := anim.Render(sprite, 0, 0)
type Color ¶
type Color struct {
R, G, B, A uint8
}
Color represents an RGBA color value for sprite tinting.
type Frame ¶
type Frame struct {
// Layers are sprite images composited to form this frame
Layers []Layer
// SoundID references a sound file (index into SoundFiles array, -1 for none)
SoundID int32
// Anchors are attachment points for weapon sprites or other sprites (v2.3+ only)
Anchors []Anchor
}
Frame represents a single animation frame.
Each frame can have multiple sprite layers composited together, optional sound effects, and anchor points for alignment.
type Header ¶
type Header struct {
// Magic should be "AC" (0x41, 0x43)
Magic [2]byte
// MinorVersion ranges from 0-5 (e.g., 2.5 has minor=5)
MinorVersion uint8
// MajorVersion is always 2 for RO ACT files
MajorVersion uint8
// ActionCount is the number of animation sequences in the file
ActionCount uint16
}
Header represents the ACT file header.
The header contains version and action count information.
func (*Header) GetVersion ¶
GetVersion returns the ACT version as a float. Examples: 2.0, 2.1, 2.2, 2.3, 2.4, 2.5
func (*Header) IsSupportedVersion ¶
IsSupportedVersion checks if this ACT version is supported by this library. Supported versions are 2.0 through 2.5.
type Layer ¶
type Layer struct {
// OffsetX is the horizontal position offset from the center
OffsetX int32
// OffsetY is the vertical position offset from the center
OffsetY int32
// SpriteIndex references which sprite frame to use from the SPR file
SpriteIndex int32
// Mirror flips the sprite horizontally if true
Mirror bool
// Color tint applied to the sprite (RGBA)
Color Color
// ScaleX is the horizontal scale factor (1.0 = normal size)
ScaleX float32
// ScaleY is the vertical scale factor (1.0 = normal size, v2.4+ only)
ScaleY float32
// Rotation angle in degrees (rotation support varies by version)
Rotation int32
// SpriteType indicates if this references an indexed or BGRA sprite
SpriteType SpriteType
// Width of the layer (v2.5+ only)
Width int32
// Height of the layer (v2.5+ only)
Height int32
}
Layer represents a single sprite layer within a frame.
Layers are rendered with transformations (position, rotation, scale, mirror, color). Multiple layers can be composed to create complex sprites.
type SpriteSheetLayout ¶
type SpriteSheetLayout int
SpriteSheetLayout defines how frames are arranged in a sprite sheet
const ( // LayoutHorizontal arranges frames in a single row LayoutHorizontal SpriteSheetLayout = iota // LayoutVertical arranges frames in a single column LayoutVertical // LayoutGrid arranges frames in a grid (auto-sized to be roughly square) LayoutGrid )
type SpriteType ¶
type SpriteType int32
SpriteType represents the type of sprite referenced by a layer
const ( // SpriteTypeIndexed8 references an Indexed8 sprite SpriteTypeIndexed8 SpriteType = 0 // SpriteTypeBgra32 references a Bgra32 sprite SpriteTypeBgra32 SpriteType = 1 )
type Version ¶
type Version float32
Version represents an ACT format version
const ( // Version20 is ACT version 2.0 (adds color, scale, rotation) Version20 Version = 2.0 // Version21 is ACT version 2.1 (adds sound files) Version21 Version = 2.1 // Version22 is ACT version 2.2 (adds animation speed per action) Version22 Version = 2.2 // Version23 is ACT version 2.3 (adds anchor points) Version23 Version = 2.3 // Version24 is ACT version 2.4 (adds separate ScaleY) Version24 Version = 2.4 // Version25 is ACT version 2.5 (adds width/height to layers) Version25 Version = 2.5 )
Source Files