PointClickEngine::Characters::Player
Inherits PointClickEngine::Characters::Talkable < PointClickEngine::Characters::Character < PointClickEngine::Characters::Talkable < PointClickEngine::Core::GameObject < PointClickEngine::Core::Drawable < Reference < Object
The main player character with inventory and interaction capabilities.
Player represents the protagonist that the user controls. It extends
Character with player-specific features like inventory access,
item usage, and special interaction callbacks. The player character
serves as the primary interface between the user and the game world.
## Features
- 8-directional walking animations
- Context-specific action animations (pick up, use, examine)
- Inventory system integration
- Movement enable/disable for scripted sequences
- Special idle and personality animations
- Interaction callbacks for game logic
## Basic Setup
```crystal
# Create player character
player = Player.new("Alex", Vector2.new(400, 300), Vector2.new(32, 48))
# Load animated sprite sheet
player.load_enhanced_spritesheet("alex_sprites.png", 32, 48, 8, 4)
# 8 columns for directions, 4 rows for animation states
# Add to scene
scene.player = player
```
## Movement Control
```crystal
# Player automatically handles click-to-walk
player.handle_click(mouse_pos, scene)
# Disable during sequences
player.movement_enabled = false
sequence.play
sequence.on_complete = -> { player.movement_enabled = true }
```
## Item Interactions
```crystal
# Using items on objects
player.use_item_on_target(door_position)
# Plays "using" animation facing the door
# Picking up items
player.pick_up_item(key_position)
# Plays "picking up" animation and faces item
# Examining objects
player.examine_object(painting_position)
# Turns to face object without moving
```
## Inventory Integration
```crystal
# Control inventory access
player.inventory_access = false # Disable during conversations
# Check for items
if player.inventory.has_item?("key")
player.use_item_on_target(door_position)
end
```
## Interaction Callbacks
```crystal
# Track what the player is interacting with
player.on_interact_with = ->(target : Hotspot | Character, verb : Symbol) {
case verb
when :use
handle_use_interaction(target)
when :look
handle_examine(target)
when :talk
start_conversation(target) if target.is_a?(Character)
end
}
```
## Common Gotchas
1. Movement during dialogs: Always disable movement during conversations
```crystal
dialog.on_show = -> { player.movement_enabled = false }
dialog.on_hide = -> { player.movement_enabled = true }
```
2. Player is not automatically added to scene: Must assign explicitly
```crystal
scene.player = player # Don't forget this!
```
3. Animation setup timing: Load spritesheet after window init
```crystal
engine.init
player.load_enhanced_spritesheet(...) # After init
```
4. Interaction callbacks not serialized: Re-register after loading
```crystal
# After loading a save:
player.interaction_callback = original_callback
```
## Customization
```crystal
class CustomPlayer < Player
property stamina : Float32 = 100.0
def walk_to(target : Vector2)
if @stamina > 0
super
@stamina -= 1.0
else
say("I'm too tired to walk!")
end
end
def rest
perform_action(AnimationState::Sitting)
@stamina = Math.min(100.0, @stamina + 50.0)
end
end
```
## Performance Notes
- Player updates every frame when visible
- Pathfinding calculations occur on click (can be expensive)
- Animation frames cached for performance
- Consider disabling when off-screen
## See Also
- Character - Base class with 8-dir animations
- Inventory::InventorySystem - Player inventory
- Scene#player - Scene player management
- Engine#player - Global player access
Constructors
new(name : String, position : RL::Vector2, size : RL::Vector2)
Sourcenew
SourceInstance methods
after_yaml_deserialize(ctx : YAML::ParseContext)
Called after YAML deserialization to restore runtime state
examine_object(object_position : RL::Vector2)
Turns character to look at an object without moving.
Useful for examine actions where the player comments on something
without walking to it. Uses idle animation in the appropriate direction.
- object_position : Position to look towards
```crystal
player.examine_object(painting.position)
player.say("A beautiful landscape painting.")
```
handle_click(mouse_pos : RL::Vector2, scene : Scenes::Scene)
Handles mouse click for player movement.
Validates the target position is walkable before initiating movement.
Automatically selects appropriate walking animation based on direction.
- mouse_pos : Click position in world coordinates
- scene : Current scene for walkability checks
```crystal
# In input handler
if mouse_clicked
player.handle_click(mouse_world_pos, current_scene)
end
```
NOTE: Respects movement_enabled flag
interaction_callback
Callback tracking current interaction target and verb (runtime only).
Used by the game logic to handle complex multi-step interactions.
Format: {target_object, verb_symbol}
interaction_callback=(interaction_callback : Tuple(Scenes::Hotspot | Character, Symbol) | Nil)
Callback tracking current interaction target and verb (runtime only).
Used by the game logic to handle complex multi-step interactions.
Format: {target_object, verb_symbol}
inventory_access
Whether the player can open their inventory.
Disable during conversations, scripted sequences, or puzzles to prevent
players from accessing items at inappropriate times.
inventory_access=(inventory_access : Bool)
Whether the player can open their inventory.
Disable during conversations, scripted sequences, or puzzles to prevent
players from accessing items at inappropriate times.
movement_enabled
Whether the player can move via mouse clicks.
Disable during dialogs or scripted sequences to
prevent unwanted movement.
movement_enabled=(movement_enabled : Bool)
Whether the player can move via mouse clicks.
Disable during dialogs or scripted sequences to
prevent unwanted movement.
pick_up_item(item_position : RL::Vector2)
Plays item pickup animation facing the item.
Character bends down or reaches out to pick up an item.
The animation varies based on item height relative to character.
- item_position : Position of the item being picked up
```crystal
player.pick_up_item(coin.position)
inventory.add_item(coin)
scene.remove_object(coin)
```
pull_object(object_position : RL::Vector2)
Sourcepush_object(object_position : RL::Vector2)
Sourceuse_item_on_target(target_position : RL::Vector2)