3. Core Game Architecture & Systems
# 3. Core Game Architecture & Systems
## Overview
The Defold Platformer Framework is built on a modular architecture that prioritizes flexibility, maintainability, and performance. This section details the core systems that power the framework and explains how they interact to create a cohesive game experience.
## Architectural Philosophy
The framework follows these key principles:
- **Component-based design**: Functionality is broken down into reusable components
- **Message-passing communication**: Systems communicate through well-defined messages
- **Data-driven configuration**: Game behaviors are controlled via external configuration
- **Separation of concerns**: Each system handles a specific aspect of gameplay
## System Architecture
The framework's architecture can be visualized as follows:
```mermaid
graph TD
A[Game Controller] --> B[Input System]
A --> C[Entity System]
A --> D[Level System]
A --> E[Camera System]
A --> F[UI System]
B --> G[Player Controller]
C --> H[Physics System]
C --> I[Animation System]
C --> J[Collision System]
G --> C
H --> J
J --> C
D --> C
```
## Core Systems
### Game Controller
The Game Controller serves as the central coordinator for all game systems. It:
- Initializes all subsystems in the correct order
- Manages game state transitions (menu, gameplay, pause)
- Handles global game events
- Controls game flow and progression
**Key Implementation**:
```lua
-- game_controller.script
function init(self)
-- Initialize core systems
msg.post("#input_system", "init")
msg.post("#entity_system", "init")
msg.post("#level_system", "init")
-- Set initial game state
self.game_state = GAME_STATES.MENU
end
function on_message(self, message_id, message, sender)
if message_id == hash("change_state") then
self.game_state = message.new_state
broadcast_state_change(self)
end
end
```
### Input System
The Input System abstracts hardware input handling, providing:
- Configurable input mapping
- Support for multiple input methods (keyboard, gamepad, touch)
- Context-sensitive input handling
- Input buffering for responsive controls
**Input Mapping Configuration**:
```lua
-- input_config.lua
return {
keyboard = {
left = {keys = {"key_a", "key_left"}, action = "move_left"},
right = {keys = {"key_d", "key_right"}, action = "move_right"},
jump = {keys = {"key_space", "key_w", "key_up"}, action = "jump"}
},
gamepad = {
left = {device = "gamepad", input = "lstick_left", action = "move_left"},
right = {device = "gamepad", input = "lstick_right", action = "move_right"},
jump = {device = "gamepad", input = "button_a", action = "jump"}
}
}
```
### Entity System
The Entity System manages all game objects and their behaviors:
- Handles entity creation, destruction, and pooling
- Coordinates component interactions
- Manages entity states and properties
- Provides a query interface for finding entities
### Physics System
The Physics System builds upon Defold's built-in physics engine with:
- Platformer-specific physics behaviors
- Configurable physics properties
- Specialized collision handling
- Performance optimizations for 2D platformers
**Physics Configuration Example**:
```lua
-- player_physics.lua
return {
gravity = 980,
max_fall_speed = 500,
jump_power = 550,
move_speed = 250,
acceleration = 2000,
deceleration = 1800,
air_control = 0.65,
coyote_time = 0.15,
jump_buffer_time = 0.12
}
```
### Collision System
The Collision System provides specialized collision detection and response for platformers:
- One-way platform handling
- Moving platform support
- Slope detection and movement
- Specialized collision responses (bounce, slide, stick)
**Collision Response Math**:
For slope movement, we calculate the adjusted velocity using:
$$v_{adjusted} = v_{horizontal} \cdot \cos(\theta) + v_{vertical} \cdot \sin(\theta)$$
Where $\theta$ is the slope angle.
### Animation System
The Animation System manages visual representations of game entities:
- State-driven animation transitions
- Animation events and callbacks
- Procedural animation effects
- Sprite sheet and skeletal animation support
**Animation State Machine**:
```mermaid
stateDiagram-v2
[*] --> Idle
Idle --> Run: movement input
Run --> Idle: no movement
Idle --> Jump: jump button
Run --> Jump: jump button
Jump --> Fall: vertical velocity < 0
Fall --> Idle: grounded + no movement
Fall --> Run: grounded + movement
Jump --> DoubleJump: jump button during jump
DoubleJump --> Fall: vertical velocity < 0
Idle --> Fall: not grounded
Run --> Fall: not grounded
```
### Camera System
The Camera System provides intelligent framing of gameplay:
- Target following with configurable parameters
- Screen transitions and effects
- Camera zones and boundaries
- Look-ahead and anticipation logic
**Camera Follow Logic**:
```lua
function update_camera(self, dt)
-- Calculate target position with look-ahead
local target_pos = go.get_position(self.target)
local target_velocity = go.get_position(self.target) - self.last_target_pos
self.last_target_pos = go.get_position(self.target)
-- Apply look-ahead based on movement direction and speed
local look_ahead = vmath.vector3()
look_ahead.x = target_velocity.x * self.look_ahead_factor
-- Calculate desired camera position with smoothing
local desired_pos = target_pos + look_ahead
local camera_pos = go.get_position()
local new_pos = vmath.lerp(self.smoothing * dt, camera_pos, desired_pos)
-- Apply camera bounds
new_pos.x = math.max(self.bounds.min_x, math.min(self.bounds.max_x, new_pos.x))
new_pos.y = math.max(self.bounds.min_y, math.min(self.bounds.max_y, new_pos.y))
go.set_position(new_pos)
end
```
### Level System
The Level System manages level loading, structure, and progression:
- Level loading and unloading
- Checkpoint and respawn management
- Level transition effects
- Dynamic level element management
## Data Flow
Data flows through the system as follows:
```mermaid
sequenceDiagram
participant Input as Input System
participant Player as Player Controller
participant Physics as Physics System
participant Collision as Collision System
participant Animation as Animation System
participant Camera as Camera System
Input->>Player: Input Actions
Player->>Physics: Movement Intent
Physics->>Collision: Position Change
Collision->>Physics: Collision Response
Physics->>Player: Updated Physics State
Player->>Animation: State Change
Player->>Camera: Position Update
```
## Performance Considerations
The framework implements several optimizations:
- **Entity pooling**: Reuses common entities to reduce garbage collection
- **Spatial partitioning**: Only processes entities in active regions
- **Message batching**: Reduces message overhead for frequent communications
- **Tiered update rates**: Updates different systems at appropriate frequencies
## Integration Points
The framework provides clear integration points for game-specific extensions:
- **Custom components**: Add new behaviors through the component system
- **Event hooks**: React to system events without modifying core code
- **Configuration overrides**: Adjust system behaviors through configuration
- **Custom systems**: Add entirely new systems that integrate with existing ones
## Next Steps
With an understanding of the core architecture, you can now explore:
- Creating and configuring entities
- Implementing custom player mechanics
- Designing levels with the provided tools
- Extending the framework with your own systems