Documentation
¶
Overview ¶
Package client provides a framework-agnostic animation controller for tangent characters.
Index ¶
- Constants
- Variables
- type QueueCondition
- type TangentClient
- func (c *TangentClient) ClearQueue()
- func (c *TangentClient) GetCharacterName() string
- func (c *TangentClient) GetColor() string
- func (c *TangentClient) GetDimensions() (width, height int)
- func (c *TangentClient) GetExpressions() []string
- func (c *TangentClient) GetFPS() int
- func (c *TangentClient) GetFrame() []string
- func (c *TangentClient) GetFrameIndex() int
- func (c *TangentClient) GetFrameRaw() []string
- func (c *TangentClient) GetIdleExpression() string
- func (c *TangentClient) GetLoopCount() int
- func (c *TangentClient) GetState() string
- func (c *TangentClient) HasState(state string) bool
- func (c *TangentClient) IsRunning() bool
- func (c *TangentClient) ListStates() []string
- func (c *TangentClient) OnLoopComplete(fn func(state string, loop int))
- func (c *TangentClient) OnStateChange(fn func(from, to string))
- func (c *TangentClient) QueueState(state string, condition QueueCondition)
- func (c *TangentClient) QueueStateWithFPS(state string, condition QueueCondition, fps int)
- func (c *TangentClient) RemoveAlias(from string)
- func (c *TangentClient) SetAlias(from, to string)
- func (c *TangentClient) SetDefaultFPS(fps int)
- func (c *TangentClient) SetExpressions(expressions []string)
- func (c *TangentClient) SetFPS(fps int)
- func (c *TangentClient) SetState(state string)
- func (c *TangentClient) SetStateFPS(state string, fps int)
- func (c *TangentClient) SetStateWithFPS(state string, fps int)
- func (c *TangentClient) Start()
- func (c *TangentClient) Stop()
- func (c *TangentClient) Tick()
Constants ¶
const ExpressionChangeInterval = 2 * time.Second
ExpressionChangeInterval controls how often idle expression changes
Variables ¶
var DefaultAliases = map[string]string{
"think": "resting",
"thinking": "resting",
"bash": "read",
"grep": "read",
"glob": "read",
"find": "read",
"edit": "write",
"editing": "write",
"writing": "write",
"reading": "read",
"success": "approval",
"complete": "approval",
"done": "approval",
"fail": "wait",
"failed": "wait",
"start": "arise",
"startup": "arise",
}
DefaultAliases maps common state names to tangent character states. These are applied automatically when SetState is called with an unrecognized name. Custom aliases set via SetAlias take precedence over these defaults.
var DefaultIdleExpressions = []string{
"hmm...",
"uhh...",
"well...",
"let me think...",
"pondering...",
"...",
"ah...",
"okay...",
"right...",
"so...",
"um...",
"erm...",
"hm.",
"thinking...",
"processing...",
"considering...",
"wait...",
"one moment...",
"let's see...",
"now then...",
"alright...",
"mhm...",
"indeed...",
"interesting...",
"curious...",
}
DefaultIdleExpressions - 25 filler phrases for agent personality Used when no active events exist (idle state)
var DefaultStateFPS = map[string]int{
"resting": 2,
"wait": 3,
"read": 4,
"write": 4,
"search": 6,
"approval": 3,
"arise": 5,
}
DefaultStateFPS provides recommended FPS for states. These can be applied via client.SetStateFPS() or used as reference.
Functions ¶
This section is empty.
Types ¶
type QueueCondition ¶
type QueueCondition interface {
// contains filtered or unexported methods
}
QueueCondition defines when a queued state should be activated.
func AfterFrames ¶
func AfterFrames(n int) QueueCondition
AfterFrames creates a condition that activates after n frames. Example: AfterFrames(10) activates after 10 frames have been shown.
func AfterLoops ¶
func AfterLoops(n int) QueueCondition
AfterLoops creates a condition that activates after n complete loops. Example: AfterLoops(2) activates after the animation loops twice.
func Immediate ¶
func Immediate() QueueCondition
Immediate creates a condition that activates on the next tick. Useful for soft transitions that wait for the current frame to complete.
type TangentClient ¶
type TangentClient struct {
// contains filtered or unexported fields
}
TangentClient is a framework-agnostic animation controller for tangent characters. It manages animation state, frame timing, and state transitions in a thread-safe manner.
Usage with tcell/tview:
tc := client.NewMicro("sam")
tc.SetStateFPS("resting", 2)
tc.SetStateFPS("write", 8)
tc.Start()
// In your render loop
frame := tc.GetFrame()
avatarView.SetText(strings.Join(frame, "\n"))
// On state change events
tc.SetState("write")
func New ¶
func New(name string) (*TangentClient, error)
New creates a TangentClient for a regular (11x4) character.
func NewMicro ¶
func NewMicro(name string) (*TangentClient, error)
NewMicro creates a TangentClient for a micro (8x2) character.
func (*TangentClient) ClearQueue ¶
func (c *TangentClient) ClearQueue()
ClearQueue removes any queued state transition.
func (*TangentClient) GetCharacterName ¶
func (c *TangentClient) GetCharacterName() string
GetCharacterName returns the character's name.
func (*TangentClient) GetColor ¶
func (c *TangentClient) GetColor() string
GetColor returns the character's hex color code.
func (*TangentClient) GetDimensions ¶
func (c *TangentClient) GetDimensions() (width, height int)
GetDimensions returns the character's width and height.
func (*TangentClient) GetExpressions ¶ added in v0.4.0
func (c *TangentClient) GetExpressions() []string
GetExpressions returns the current expressions list.
func (*TangentClient) GetFPS ¶
func (c *TangentClient) GetFPS() int
GetFPS returns the current effective FPS. Priority: override > state-specific > default.
func (*TangentClient) GetFrame ¶
func (c *TangentClient) GetFrame() []string
GetFrame returns the current animation frame as pre-colored lines. This is safe to call from any goroutine. For micro avatars (8x2), applies random color flicker effect.
func (*TangentClient) GetFrameIndex ¶
func (c *TangentClient) GetFrameIndex() int
GetFrameIndex returns the current frame index within the animation.
func (*TangentClient) GetFrameRaw ¶
func (c *TangentClient) GetFrameRaw() []string
GetFrameRaw returns the current frame without color codes. Useful when applying custom colors.
func (*TangentClient) GetIdleExpression ¶ added in v0.4.0
func (c *TangentClient) GetIdleExpression() string
GetIdleExpression returns current idle expression, changing every 2s. Use this for status text when no active events exist.
func (*TangentClient) GetLoopCount ¶
func (c *TangentClient) GetLoopCount() int
GetLoopCount returns the number of completed loops for the current state.
func (*TangentClient) GetState ¶
func (c *TangentClient) GetState() string
GetState returns the current animation state name.
func (*TangentClient) HasState ¶
func (c *TangentClient) HasState(state string) bool
HasState returns true if the state exists (checking aliases).
func (*TangentClient) IsRunning ¶
func (c *TangentClient) IsRunning() bool
IsRunning returns true if the internal ticker is active.
func (*TangentClient) ListStates ¶
func (c *TangentClient) ListStates() []string
ListStates returns all available state names.
func (*TangentClient) OnLoopComplete ¶
func (c *TangentClient) OnLoopComplete(fn func(state string, loop int))
OnLoopComplete sets a callback invoked when an animation loop completes. Called in a separate goroutine to avoid blocking.
func (*TangentClient) OnStateChange ¶
func (c *TangentClient) OnStateChange(fn func(from, to string))
OnStateChange sets a callback invoked when the state changes. The callback receives the old and new state names. Called in a separate goroutine to avoid blocking.
func (*TangentClient) QueueState ¶
func (c *TangentClient) QueueState(state string, condition QueueCondition)
QueueState queues a state transition that will occur when the condition is met. Only one state can be queued at a time; calling again replaces the queue.
func (*TangentClient) QueueStateWithFPS ¶
func (c *TangentClient) QueueStateWithFPS(state string, condition QueueCondition, fps int)
QueueStateWithFPS queues a state transition with a specific FPS override.
func (*TangentClient) RemoveAlias ¶
func (c *TangentClient) RemoveAlias(from string)
RemoveAlias removes a custom alias.
func (*TangentClient) SetAlias ¶
func (c *TangentClient) SetAlias(from, to string)
SetAlias adds a custom state alias. Custom aliases take precedence over defaults.
func (*TangentClient) SetDefaultFPS ¶
func (c *TangentClient) SetDefaultFPS(fps int)
SetDefaultFPS sets the fallback FPS used when no state-specific FPS is configured.
func (*TangentClient) SetExpressions ¶ added in v0.4.0
func (c *TangentClient) SetExpressions(expressions []string)
SetExpressions allows custom expressions (for per-agent personality).
func (*TangentClient) SetFPS ¶
func (c *TangentClient) SetFPS(fps int)
SetFPS temporarily overrides the current FPS (cleared on state change).
func (*TangentClient) SetState ¶
func (c *TangentClient) SetState(state string)
SetState changes the current animation state immediately. The state name is resolved through aliases (custom first, then defaults). Resets frame index and loop count. Triggers OnStateChange callback if set.
func (*TangentClient) SetStateFPS ¶
func (c *TangentClient) SetStateFPS(state string, fps int)
SetStateFPS configures the FPS for a specific state.
func (*TangentClient) SetStateWithFPS ¶
func (c *TangentClient) SetStateWithFPS(state string, fps int)
SetStateWithFPS changes state and temporarily overrides FPS for this state activation.
func (*TangentClient) Start ¶
func (c *TangentClient) Start()
Start begins automatic frame advancement using an internal ticker. The ticker rate is based on the current effective FPS.
func (*TangentClient) Tick ¶
func (c *TangentClient) Tick()
Tick advances the animation by one frame. Call this at your desired frame rate when not using Start(). Processes queued state transitions and triggers callbacks.
Source Files