Characters

Characters are the actors in your game world. They can be player-controlled protagonists, switchable crew mates, or non-player characters (NPCs) with autonomous behaviors.

Table of Contents

• Overview
• Creating a Character
• Configuration Fields
• Character Types
• Directional Sprites
• NPC Behaviors
• Best Practices
• Examples

Overview

Post Type: explore-character

Characters bring life to your game world. The system supports sophisticated character configuration including directional character images, weapon-specific character images, special abilities, and complex AI behaviors for NPCs.

Key Features

• Full directional character image support (up, down, left, right)
• Weapon-specific character images for each direction
• Playable characters and crew mate system
• NPC autonomous behaviors (wandering, pathing)
• Text-to-speech voice assignment
• Materialization and removal systems
• Interaction with cutscenes and missions

Creating a Character

1. Navigate to Orbem Studio → Characters
2. Click Add New
3. Enter a character name (this becomes the display name)
4. Configure meta fields in the Configuration box
5. Upload character images for all required directions
6. Click Publish

Configuration Fields

Basic Configuration

Area Placement

Field: explore-area
Type: Select

The area where this character appears in the game world.

Example: Select "starting-village" to place the character in that area.

Position and Size

Fields:

• explore-top - Vertical position in pixels
• explore-left - Horizontal position in pixels
• explore-height - Character height in pixels
• explore-width - Character width in pixels

Example:

Top: 2000
Left: 2500
Height: 100
Width: 80

Visual Properties

Field: explore-rotation
Type: Number
Unit: Degrees

Rotate the character sprite (useful for angled starting poses).

Field: explore-layer
Type: Number

Z-index for layering. Higher numbers appear in front of lower numbers.

Example:

Rotation: 0 (no rotation)
Layer: 5 (appears above objects with layer < 5)

Character Name Override

Field: explore-character-name
Type: Text

Display name shown to players. If empty, uses the post title.

Use Cases:

• Show formatted names with special characters
• Support multiple languages
• Display nicknames or aliases
• Keep backend titles clean while showing styled names

Example:

Post Title: hero-character-01
Character Name: "The Wandering Hero"

Character Images

Field: explore-character-images
Type: Multiple uploads (subfields)

The core visual representation of your character. You must upload images for all directions and states.

Required Images

Static Poses (Standing Still):

• static-up - Facing upward (away from camera)
• static-down - Facing downward (toward camera)
• static-left - Facing left
• static-right - Facing right

Walking Animations:

• up - Walking upward
• down - Walking downward
• left - Walking left
• right - Walking right

Static Drag Poses (Optional - for carrying items):

• static-up-drag - Standing still while carrying, facing up
• static-left-drag - Standing still while carrying, facing left
• static-right-drag - Standing still while carrying, facing right

Dragging Animations (Optional):

• up-drag - Walking while carrying, upward
• left-drag - Walking while carrying, left
• right-drag - Walking while carrying, right

Combat Poses (for playable characters):

• up-punch - Attacking upward
• down-punch - Attacking downward
• left-punch - Attacking left
• right-punch - Attacking right

Image Specifications

• Format: PNG (with transparency) or GIF (for animations)
• Dimensions: Consistent across all images (e.g., 80px × 100px)
• Animation: Use GIF for walking animations, PNG for static poses
• Transparency: Use alpha channel for non-rectangular sprites

Tips:

• Keep file sizes small for faster loading
• Use the same dimensions for all images to prevent scaling issues
• Test all animations in-game to verify smoothness
• Consider creating sprite sheets and slicing them for consistency

Weapon-Specific Images

Field: explore-weapon-images
Type: Multiple uploads (dynamic based on available weapons)

For playable characters, you can upload unique images for each weapon they can equip.

The field automatically generates upload slots for each weapon (except the default weapon) combined with each character pose:

Example weapon-specific image fields:

• static-sword - Standing still with sword
• up-sword - Walking up with sword
• down-punch-sword - Attacking down with sword
• static-laser-gun - Standing still with laser gun
• left-punch-laser-gun - Attacking left with laser gun

How It Works:

1. Plugin detects all weapons in your game
2. For each weapon (except default), creates image upload fields
3. Combines weapon names with character poses

Note: Only required for playable characters. NPCs don't use weapon-specific images.

Playable Character Settings

Crew Mate Status

Field: explore-crew-mate
Type: Radio (yes or no)

Determines if this character can be controlled by the player.

• Yes: Character is playable (can collected as crew mate upon first appearance. Is usable after that.)
• No: Character is an NPC with autonomous behavior

Example:

Crew Mate: yes (This is the main hero)

Special Ability

Field: explore-ability
Type: Select

Assign a special ability to playable characters.

Available Abilities:

• speed - Increased movement speed
• strength - Can drag/break/collect heavy items
• hazard - Can walk through hazardous areas (for a limited time)
• programming - Can interact with technical objects

Example:

Ability: hazard (Can walk through toxic zones)

Use Cases:

• Gating areas behind specific abilities
• Creating puzzles that require ability switching
• Character specialization in party-based gameplay

Default Weapon

Field: explore-weapon-choice
Type: Select (list of weapons)

The weapon this character starts with when first recruited or played.

Example:

Weapon Choice: energy-sword

Voice Configuration

Field: explore-voice
Type: Select (Google TTS voices)

Assign a text-to-speech voice for cutscene dialogue.

Requirements:

• Google TTS API key configured in Global Options
• Voice selection from available Google voices

Available Voice Types:

• Male and female voices
• Multiple languages
• Different voice styles (standard, wavenet, neural)

Example:

Voice: en-US-Wavenet-D (Female voice)

See Cutscenes for how voices are used in dialogue.

NPC Configuration

These settings control autonomous NPC behavior.

Movement Speed

Field: explore-speed
Type: Number

How fast the NPC moves. Lower values = faster movement.

Example:

Speed: 20 (Moderate pace)
Speed: 10 (Fast movement)
Speed: 40 (Slow movement)

Tips:

• Match speed to character personality (elderly = slow, energetic = fast)
• Consider gameplay balance (fleeing NPCs, chase sequences)
• Test speeds in context of area size

Wanderer Mode

Field: explore-wanderer
Type: Radio (yes or no)

Enable intelligent autonomous movement throughout the area.

• Yes: NPC automatically explores available walkable space
• No: NPC follows defined path or stays stationary

Wanderer Behavior:

• Intelligently navigates the area
• Avoids walls and boundaries
• Changes direction randomly
• Creates lifelike ambient movement

Use Cases:

• Villagers wandering in a town
• Animals roaming in a forest
• Guards on patrol

Example:

Wanderer: yes
Speed: 20

Walking Path

Field: explore-path
Type: Repeater (multiple coordinate pairs)

Define a specific path the NPC follows.

Structure:

Point 1: Top: 2000, Left: 2500
Point 2: Top: 2000, Left: 3000
Point 3: Top: 2500, Left: 3000
Point 4: Top: 2500, Left: 2500

Behavior:

• NPC walks to each point in sequence
• Uses configured speed for movement
• Can optionally repeat after reaching the end

Tips:

• Use Developer Mode to set path points visually
• Keep paths smooth with reasonable distances between points
• Test path timing to ensure NPC reaches destinations

Path Repeat

Field: explore-repeat
Type: Radio (yes or no)

Control if the NPC repeats their walking path.

• Yes: Loop back to start after reaching the end
• No: Stop at the final point

Example:

Path: [4 points forming a square]
Repeat: yes
(NPC walks in a continuous square pattern)

Time Between Paths

Field: explore-time-between
Type: Number
Unit: Milliseconds

Pause duration at each path point before moving to the next.

Example:

Time Between: 2000 (2 second pause at each point)
Time Between: 0 (No pause, continuous movement)

Use Cases:

• Guard pausing to look around at patrol points
• NPC stopping to perform actions
• Creating more natural movement patterns

Path Trigger

Field: explore-path-trigger
Type: Complex object

Define a trigger zone that starts the NPC's movement path.

Subfields:

• top - Trigger top position
• left - Trigger left position
• height - Trigger height
• width - Trigger width
• cutscene - Cutscene that activates this path
• item - Item that activates this path

Example Use Case:

NPC stands still until player completes a cutscene,
then begins walking their defined path.

Path Trigger:
  Cutscene: welcome-dialogue
  (NPC starts moving after "welcome-dialogue" completes)

Materialization System

Control when and how characters appear in the game world.

Materialize Trigger

Field: explore-materialize-item-trigger
Type: Trigger zone

A physical zone that reveals this character when touched.

Subfields:

• top - Trigger top coordinate
• left - Trigger left coordinate
• height - Trigger height
• width - Trigger width

Example:

Character is hidden until player walks to a specific location,
then character materializes.

Materialize Trigger:
  Top: 3000
  Left: 3500
  Height: 100
  Width: 100

Materialize After Cutscene

Field: explore-materialize-after-cutscene
Type: Select (list of cutscenes)

Character appears after a specific cutscene completes.

Example:

Materialize After Cutscene: rescue-scene
(Character appears after being rescued in cutscene)

Materialize After Mission

Field: explore-materialize-after-mission
Type: Select (list of missions)

Character appears after a specific mission is completed.

Example:

Materialize After Mission: find-the-key
(NPC appears after player completes the mission)

Remove After Cutscene

Field: explore-remove-after-cutscene
Type: Select (list of cutscenes)

Character disappears after a specific cutscene completes.

Example:

Remove After Cutscene: farewell-scene
(NPC leaves the game world after saying goodbye)

Character Types

Main Character

The primary player-controlled character.

Configuration:

Crew Mate: no
Top: 0
Left: 0
Ability: (choose primary ability)
Weapon Choice: (starting weapon)
Voice: (for cutscene dialogue)

Required Images: All directional sprites + weapon variants

Set as Main Character: Go to Orbem Studio → Game Options → Main Character and select this character.

Crew Mate

Additional playable characters the player can collect and switch between.

Configuration:

Crew Mate: yes
Ability: (unique ability)
Weapon Choice: (default weapon)
Voice: (for cutscene dialogue)

Required Images: All directional sprites + weapon variants

Recruitment: Use missions or cutscenes to add crew mates to the player's roster. See API endpoints for programmatic recruitment.

Static NPC

NPC that doesn't move, used for shopkeepers, quest givers, etc.

Configuration:

Crew Mate: no
Wanderer: no
Path: (empty)

Required Images: Static poses only (can skip walking animations)

Use Cases:

• Shopkeepers behind counters
• Statues or decorative characters
• Quest givers who never move

Wandering NPC

NPC that roams freely throughout the area.

Configuration:

Crew Mate: no
Wanderer: yes
Speed: 2

Required Images: All directional sprites

Use Cases:

• Townspeople
• Animals
• Ambient life

Pathing NPC

NPC that follows a predefined walking path.

Configuration:

Crew Mate: no
Wanderer: no
Path: [multiple points]
Repeat: yes
Speed: 2

Required Images: All directional sprites

Use Cases:

• Guards on patrol
• NPCs with routines
• Escort missions

Directional Sprites

The character sprite system supports full 4-directional movement with multiple states.

Sprite State Machine

stateDiagram-v2
    [*] --> StaticDown
    StaticDown --> WalkingDown: Move Down
    StaticDown --> WalkingUp: Move Up
    StaticDown --> WalkingLeft: Move Left
    StaticDown --> WalkingRight: Move Right

    WalkingDown --> StaticDown: Stop
    WalkingUp --> StaticUp: Stop
    WalkingLeft --> StaticLeft: Stop
    WalkingRight --> StaticRight: Stop

    StaticDown --> AttackDown: Attack
    StaticUp --> AttackUp: Attack
    StaticLeft --> AttackLeft: Attack
    StaticRight --> AttackRight: Attack

    AttackDown --> StaticDown: Attack Complete
    AttackUp --> StaticUp: Attack Complete
    AttackLeft --> StaticLeft: Attack Complete
    AttackRight --> StaticRight: Attack Complete

Image Naming Convention

Character images follow this pattern:

[state]-[direction]-[weapon]

Examples:
static-down          (Standing still, facing down, default weapon)
up                   (Walking up, default weapon)
down-punch-sword     (Attacking down with sword)
static-left-gun      (Standing left with gun)

Creating Consistent Sprites

Dimensions:

• Use the same pixel dimensions for all images
• Common sizes: 64×64, 80×100, 100×120

Orientation:

• Down = facing toward screen/player
• Up = facing away from screen/player
• Left/Right = profile views

Animation Frames:

• GIFs can contain multiple frames for smooth animation
• Typical walking cycle: 4-8 frames
• Attack animations: 2-4 frames

Transparency:

• Use PNG alpha channel or GIF transparency
• Ensure background is fully transparent

NPC Behaviors

Wanderer Intelligence

When explore-wanderer is "yes", NPCs use pathfinding to explore the area.

Algorithm:

1. Check available directions (not blocked by walls)
2. Randomly select a direction
3. Move in that direction for a random duration
4. Repeat

Tips:

• Add walls to guide wanderer movement
• Set appropriate speed for area size
• Test with multiple wanderers to ensure they don't cluster

Path Following

NPCs follow defined paths precisely.

Best Practices:

• Keep path segments short for smooth movement
• Add pause points (explore-time-between) at corners
• Test paths for collision with walls
• Consider looping vs. one-way paths

Trigger-Based Movement

Use explore-path-trigger to start NPC movement conditionally.

Scenarios:

• NPC starts walking after player triggers a cutscene
• NPC begins patrol after player collects an item
• NPC flees when a mission is completed

Best Practices

Image Organization

File Naming:

hero-static-down.png
hero-walk-up.gif
hero-attack-left-sword.png

Directory Structure:

/characters/
  /hero/
    static-down.png
    static-up.png
    walk-down.gif
    ...
  /guard/
    static-down.png
    ...

Performance Optimization

File Sizes:

• Compress images without visible quality loss
• Keep GIF frame counts reasonable (4-8 frames typically)
• Total character image set should be under 1MB

Loading Strategy:

• Load playable characters first
• Lazy-load NPC images
• Preload images for areas the player is moving toward

Gameplay Design

Character Differentiation:

• Give each crew mate unique abilities
• Match abilities to puzzle design
• Create reasons to switch between characters

NPC Personality:

• Match movement speed to character personality
• Use wandering for casual NPCs, paths for intentional ones
• Position NPCs near relevant locations (shopkeeper near shop)

Examples

Example 1: Main Hero Character

Title: Main Hero
Slug: main-hero

Area: none
Top: 0
Left: 0
Height: 100
Width: 80

Crew Mate: no
Ability: strength
Weapon Choice: starter-sword
Voice: en-US-Wavenet-A

Images: All directional sprites + weapon variants uploaded

Example 2: Wandering Villager

Title: Village Elder
Slug: village-elder

Area: starting-village
Top: 3000
Left: 3200
Height: 100
Width: 80

Crew Mate: no
Wanderer: yes
Speed: 1
Voice: en-US-Wavenet-C

Images: All directional sprites uploaded

Example 3: Patrolling Guard

Title: Castle Guard
Slug: castle-guard

Area: castle-entrance
Top: 2000
Left: 2500
Height: 110
Width: 85

Crew Mate: no
Speed: 2
Path:
  Point 1: Top: 2000, Left: 2500
  Point 2: Top: 2000, Left: 3500
  Point 3: Top: 2500, Left: 3500
  Point 4: Top: 2500, Left: 2500
Repeat: yes
Time Between: 1500

Images: All directional sprites uploaded

Example 4: Recruitable Crew Mate

Title: Tech Specialist
Slug: tech-specialist

Area: research-lab
Top: 1800
Left: 2200
Height: 95
Width: 78

Crew Mate: yes
Ability: programming
Weapon Choice: laser-pistol
Voice: en-US-Wavenet-D

Materialize After Mission: rescue-specialist

Images: All directional sprites + weapon variants uploaded

Related Documentation

• Areas - Where characters exist
• Weapons - What characters equip
• Cutscenes - Character interactions
• Missions - Character recruitment
• Developer Mode - Visual character positioning