For HarmonyOS game development, the core goal is not just to “get it running” but to build a codebase that can continue to evolve. This article distills the minimum viable loop of an extensible architecture: layering, state-driven design, a System mechanism layer, and plugin-based extension. Together, these patterns solve bloated pages, difficult feature expansion, and multi-device complexity. Keywords: HarmonyOS, game architecture, plugin architecture.
Technical Specification Snapshot
| Parameter | Description |
|---|---|
| Target Platform | HarmonyOS / HarmonyOS games |
| Primary Language | ArkTS / TypeScript-style syntax |
| Architecture Pattern | Layered architecture, state-driven design, plugin architecture |
| Runtime Concerns | Multi-device adaptation, AI extensibility, maintainability |
| Collaboration Model | UI and logic decoupling, pluggable Systems |
| Star Count | Not provided in the original article |
| Core Dependencies | Store, Service, System, Plugin abstractions |
AI Visual Insight: This image serves as a thematic lead-in, emphasizing that the article focuses on HarmonyOS game architecture design. As a cover-style visual, its role is to establish the reading context of “game development + architecture governance” rather than communicate specific API details.
AI Visual Insight: This animated image resembles a process or effect demo. It is well suited to illustrating dynamic state transitions in a game UI, interaction feedback, or collaboration across modules, reinforcing the article’s technical argument that architecture must support continuously changing scenarios.
The core criterion of an extensible architecture is whether it supports long-term evolution
Many HarmonyOS game projects begin with only pages, components, and utils. At a small-project stage, the problems are not obvious. But once gameplay systems, live events, AI capabilities, and multi-device support start to accumulate, pages quickly become bloated.
Typical symptoms include single pages growing to thousands of lines, changes affecting one another, logic becoming impossible to reuse, and TV-specific and touch-device branches scattered everywhere. At that point, the issue is not weak coding ability. It is failed architectural boundaries.
// Anti-pattern: the page takes on every responsibility
@Entry
@Component
struct GamePage {
@State score: number = 0
aboutToAppear() {
this.initGame() // The page lifecycle directly drives all initialization
}
initGame() {}
update() {} // Game logic
requestData() {} // Network request
renderEnemy() {} // Partial rendering logic
build() {
Text(`Score: ${this.score}`)
}
}The problem with this code is not whether it runs. The problem is that UI, state, business logic, and runtime mechanisms are all coupled together, making safe extension nearly impossible.
An extensible architecture must provide four capabilities at the same time
First, modules must be decomposable. Second, state must be controllable. Third, logic must be reusable. Fourth, capabilities must be extensible. If any one of these is missing, refactoring costs will surface later.
// Recommended directory layout: define responsibility boundaries first
entry/
pages/ // Page layer: handles presentation and interaction orchestration only
components/ // Component layer: reusable UI units
store/ // State layer: single source of truth
services/ // Service layer: business logic, requests, AI calls
systems/ // System layer: game mechanism updates
models/ // Data models
utils/ // Shared utilitiesThis directory structure is not formalism. It is the foundation for future team collaboration, layer-based testing, and layer-based replacement.
The key value of layered design is isolating change in the right place
The Page layer handles rendering and interaction entry points only. The Component layer owns UI reuse. The Store layer centralizes state. The Service layer carries business capabilities. The System layer maintains game mechanisms. The Model layer defines data structures.
What really matters is not the number of layers but who is responsible for change. Device changes should not pollute the business layer. Gameplay changes should not leak back into the page layer. AI integration should not be hardcoded directly into components.
// State layer: establish a single source of truth
class GameStore {
score: number = 0
playerHP: number = 100
currentLevel: number = 1
}
export const gameStore = new GameStore()The value of this code is that it centralizes state. Pages no longer need to pass values everywhere, and logic gains a unified read/write entry point.
State-driven design allows the UI to react to data instead of managing business logic
In HarmonyOS games, the UI works best as a result renderer, not as a business logic command center. Pages should only consume state, while business changes should be updated by the Service or System layer.
// The page reads state only and does not embed business rules directly
@Component
struct HUDView {
build() {
Column() {
Text(`Score: ${gameStore.score}`)
Text(`HP: ${gameStore.playerHP}`)
}
}
}This significantly reduces page complexity and turns the debugging path into a one-way flow: state change -> view refresh.
The Service layer should own business logic and external capabilities
The Service layer is the right place for combat calculations, level configuration loading, network requests, leaderboard synchronization, and AI inference calls. Writing this logic directly in pages only makes the interaction layer increasingly fragile.
// Service layer: encapsulate concrete business capabilities
export class BattleService {
attack(player: { attack: number }, enemy: { hp: number }) {
enemy.hp -= player.attack // Core logic: reduce enemy HP
return enemy.hp
}
}Its value lies in reuse and testability. If you later switch AI combat strategies or change the data source, the page layer does not need to know.
The System layer is the most overlooked mechanism core in game architecture
If the Service layer answers “what business should be done,” the System layer answers “how the mechanism advances every frame or every turn.” Collision, damage, buffs, and entity spawning are all better placed in Systems.
// System layer: advance game mechanisms in a unified way
export class CombatSystem {
update(state: GameStore) {
this.handleCollision(state) // Handle collision detection
this.handleDamage(state) // Handle damage resolution
}
handleCollision(state: GameStore) {}
handleDamage(state: GameStore) {}
}
const systems = [new CombatSystem()]
systems.forEach(system => system.update(gameStore))With this design, adding a new mechanic usually means adding one more System instead of modifying a giant page.
The goal of component decomposition is not to split more, but to create clear reuse boundaries
The wrong approach is to place all UI inside one page. The right approach is to split the UI into stable units such as Player, Enemy, HUD, and Panel, with the page only assembling them.
@Component
export struct PlayerView {
@Prop hp: number
build() {
Text(`HP: ${this.hp}`) // Core logic: render player HP from the input prop
}
}
// Compose components in the page
PlayerView({ hp: gameStore.playerHP })Once components stabilize, visual iteration and gameplay changes can be partially decoupled, and team collaboration costs also decrease.
Plugin-based design determines whether AI and new gameplay can be integrated at low cost
HarmonyOS games will likely integrate NPC AI, automated testing, recommendation strategies, and dynamic event systems in the future. If these capabilities are embedded directly into core pages, every upgrade will affect the entire system.
// Plugin interface: define the boundary of extensible capabilities
interface GamePlugin {
init(): void
update(): void
}
class AIPlugin implements GamePlugin {
init(): void {}
update(): void {
// Core logic: execute AI behavior inside an isolated plugin
}
}
const plugins: GamePlugin[] = []
plugins.push(new AIPlugin())The essence of plugin architecture is not that it is an advanced pattern. It is that new capabilities are removed from the core execution path.
Multi-device adaptation should live in an adaptation layer instead of polluting the business layer
HarmonyOS targets phones, tablets, PCs, TVs, and more. A truly maintainable design isolates input methods, layout differences, and performance strategies in an adaptation layer, while the business layer focuses only on game rules.
// Adaptation layer: switch interaction strategies based on device capabilities
function setupInput(device: string) {
if (device === 'tv') {
useRemoteControl() // TV: remote control input
} else {
useTouch() // Touch devices: touch input
}
}This example shows that device differences should be injected through adaptation strategies instead of being scattered across conditional branches in every page.
Architecture evolution should be completed in stages instead of all at once
In practice, you can move forward in four steps: first validate quickly during the demo stage; then split Page and Service; then introduce Store; and finally complete the design with System and Plugin. This approach controls cost and avoids overengineering.
The full flow can be summarized as follows: user actions trigger state changes, the System layer advances runtime mechanisms, the Service layer provides business capabilities, the UI re-renders based on state, and Plugins extend new capabilities outside the core boundary.
FAQ
1. Does a HarmonyOS game project need a complete layered architecture from the beginning?
Not necessarily. An early demo can stay lightweight, but you should at least reserve room to evolve toward Page, Service, and Store separation. Otherwise, once requirements grow, giant pages will become a liability.
2. What is the biggest difference between Service and System?
Service is oriented toward business capabilities and external calls, such as combat APIs, configuration loading, and AI requests. System is oriented toward mechanism progression, such as collision handling, damage resolution, spawning, and rule settlement.
3. Why is plugin architecture especially important for AI scenarios?
Because AI capabilities change quickly, involve many dependencies, and often require frequent strategy updates. Plugin architecture lets you integrate, replace, and roll out AI capabilities independently without modifying the core business path.
Core takeaway: This article reconstructs the core method for HarmonyOS game architecture design around layering, state-driven design, Service, System, plugin architecture, and multi-device adaptation, helping developers evolve from single-page logic piles to a maintainable, reusable, and extensible HarmonyOS game engineering system.