Features

GPS World Map

The GPS World Map is the beating heart of Hidden Realms — the bridge between the real world and the game world. Instead of a fictional level or a pre-built dungeon, your actual city becomes the game map.

HOW WE IMPLEMENTED IT

We built the world map using the MapLibre Android SDK (v11.5.2), a high-performance open-source mapping engine, styled with a fully custom dark fantasy JSON theme. Every road, building, and district in your city is re-rendered in deep navy blues, glowing purples, and ancient stone textures — making your neighbourhood feel like a realm from another age.

For live location, we use Google Play Services' Fused Location Provider API. This fuses GPS satellite data with Wi-Fi and cell-tower signals to produce the most accurate, battery-efficient location possible — updating your position in real time as you walk.

HOW NODE SPAWNING WORKS

Our custom WorldSpawnerSystem runs continuously in the background. Every time you move a meaningful distance, it reads your current GPS coordinates and passes them to a deterministic seeded algorithm. This seed — derived from your real-world GPS grid cell (each roughly 50m × 50m) — generates a fresh batch of 3–5 mystical nodes within 50–250m of your actual position.

Because the seed is tied to your real-world grid, nodes appear consistently near the same local landmarks — your nearest park bench, a specific street corner, a local shop. They respawn after collection, so exploration never runs dry.

TWO NODE TYPES:

▸ TREASURE Nodes (88% spawn chance)

Glowing gold chest icons on the dark map. Walk within 30m, tap to collect instantly.

Each yields XP, Gold coins, and a loot item rolled against the rarity table.

▸ PORTAL Nodes (12% spawn chance)

Pulsing purple swirl icons — boss gates. Tapping one opens the AR Camera, where

you must physically locate and capture the portal to trigger the boss encounter.

RARITY ROLLS PER NODE:

Treasure → 60% Common / 30% Rare / 9% Epic / 1% Legendary

Portal → 55% Common / 30% Rare / 12% Epic / 3% Legendary

WHY THIS MATTERS

The GPS world map turns a passive mobile game into a reason to step outside. The only way to find more nodes, higher-rarity portals, and better loot is to physically walk around. Distance and exploration are the core progression mechanics.

AR Camera Mode

The AR Camera Mode transforms your phone into a mystical detection device. When you tap a Portal node on the world map, the game hands over control to your device's camera — and the fantasy begins bleeding into reality.

HOW WE IMPLEMENTED IT

The AR system is built on SceneView's ARSceneView — a high-level Jetpack Compose-compatible wrapper over Google ARCore. ARCore continuously tracks the physical geometry of the world around you (walls, floors, open space) using your camera's visual feed. On top of this tracked surface, we render a 3D glowing portal object anchored to a real-world coordinate tied to the GPS node's position.

The portal exists in 3D space. If you're facing the wrong direction, you simply cannot see it. You have to turn your body, move around, and search.

THE RADAR HUD

To help players find the portal, we implemented an animated Radar HUD at the top of the screen. This HUD reads the angular offset between where your camera is pointed and where the portal is located in space, then renders animated directional arrows that tighten as you turn toward the target. When the portal enters your field of view directly, the arrows converge and a pulsing "TARGET LOCKED" ring fires — cyan expanding circles with a tone, confirming the lock.

Hit CAPTURE and a cinematic portal-tear effect plays, transitioning you directly into the boss battle.

THE AMBIENT TREASURE SYSTEM

While in AR mode, the camera also spawns ambient floating treasure orbs in the real-world space around you. These are reward pickings for explorers who keep the AR camera open while moving. The spawn system is intelligent:

▸ Orbs only respawn if you have moved at least 4 metres from the last spawn point — encouraging real movement.

▸ If you stand completely still, the spawn rate drops to once every 15 seconds — actively discouraging camping in one spot.

▸ Each collected orb grants real XP and Gold coins that are saved permanently to your profile.

TECHNICAL ARCHITECTURE

The AR system uses an AtomicReference<NodeSignal> for thread-safe communication between ARCore's OpenGL render thread and Jetpack Compose's UI thread. This prevents race conditions during the critical node-detection window and ensures zero frame drops or visual glitching even on mid-range Android devices.

Boss Combat System

The Boss Combat System is the technical centrepiece of Hidden Realms — a full real-time game engine built entirely inside a Kotlin Coroutine, running at 60 frames per second on a 16ms tick loop.

HOW WE IMPLEMENTED IT

Every battle runs a single BattleEngine coroutine managing five parallel systems simultaneously: player input buffering, boss AI state machine, stagger meter, phase transition detection, and the visual effects queue. All of this is coordinated without blocking the UI thread, keeping the Compose UI perfectly smooth throughout.

PLAYER ACTIONS:

▸ TAP — Basic Attack

Each tap lands a hit and builds your Combo Multiplier. Land 10+ consecutive hits to reach the maximum ×1.5 multiplier. Miss, get hit, or lose rhythm — it resets.

▸ HOLD — Charge Attack

A slow, deliberate windup strike that deals high stagger damage. The only reliable way to break a boss out of its shielded Phase 2 stance.

▸ SWIPE — Dodge Roll

Grants 500ms of true invulnerability (no damage taken, no staggers). Swipe within 100ms of an incoming boss attack for a Perfect Dodge — triggering 300ms of slow motion, a cyan screen tint, and a combo reset bonus.

▸ POTION — Emergency Heal

Restores 30% of your Max HP instantly. Limited to 3 uses per battle by default.

THE BOSS AI — 3-PHASE STATE MACHINE:

Each of the 8 bosses runs a pattern state machine cycling through: CHARGING, PROJECTILE, AREA_BLAST, MULTI_HIT, and HEAVY_STRIKE. As the boss's HP drops, new phases unlock with faster timings and new attack combinations:

Phase 1 (100%→60% HP) — Standard attack patterns. Designed to teach the player.
Phase 2 (60%→30% HP) — +20% damage output, faster charge timings, shield phases begin.
Phase 3 (<30% HP) — ENRAGED: 0.5× timing multiplier, exclusive special attacks activate.

THE ANTI-SPAM SYSTEM:

Hidden Realms actively punishes button mashing. The SpamDetector records the timestamp of each of the last 5 hits using System.currentTimeMillis(). If 5 or more hits land within any 2-second window, the boss enters a glowing COUNTERING state — a visible 800ms windup — followed by an unblockable Counter Strike. This forces players to fight with rhythm and intention, not speed.

DAMAGE CALCULATION:

finalDmg = (playerATK × comboMultiplier) − bossCurrentDEF
Skills can modify both the multiplier and whether the hit bypasses boss defences entirely.

WHY 8 UNIQUE BOSSES?

Each boss is visually distinct (rendered via MP4 video backgrounds at ~3.5MB each) and has a unique mix of attack patterns and phase timing. No two boss fights feel the same — a skeletal archer plays completely differently from an armoured stone golem.

Skill System

The Skill System gives players active, strategic abilities that go far beyond basic tapping. Skills are power moves — high-risk, high-reward tools that must be used at the right moment and managed carefully through an Energy economy.

HOW WE IMPLEMENTED IT

Skills are managed by the SkillSystem and SkillRegistry modules. The SkillRegistry holds the definition of every skill — its damage multiplier, energy cost, cooldown timer, category, and unlock level. The SkillSystem applies these in real time during the battle loop, checking the player's current Energy, validating the cooldown, calculating the output, and updating the BattleState immutably.

Energy regenerates automatically at 5 points per second during battle. Every skill use drains Energy. Running out means waiting. Managing your Energy — when to hold it, when to spend it — is a core skill expression.

THE 5 ACTIVE SKILLS:

▸ Void Slash (Unlocks at Level 3)

Category: ATTACK | Energy Cost: 20 | Cooldown: 6 seconds . A swift void-powered slash dealing 2× your base ATK damage. Fast, cheap, and reliable — the bread-and-butter offensive skill for early and mid-game players.

▸ Energy Burst (Unlocks at Level 8)

Category: ATTACK | Energy Cost: 35 | Cooldown: 10 seconds . An explosive area burst dealing 2.5× ATK. Crucially, Energy Burst is the only skill that BYPASSES the boss's Phase 2 shields entirely — making it essential when facing shielded bosses in their defensive stance.

▸ Shield Pulse (Unlocks at Level 10)

Category: DEFENSE | Energy Cost: 30 | Cooldown: 14 seconds . Fires a defensive pulse that restores 30% of your Max HP instantly. No damage

dealt — this is a pure survival tool for moments when the boss is overwhelming and your potions are already spent.

▸ Shadow Dash (Unlocks at Level 15)

Category: UTILITY | Energy Cost: 15 | Cooldown: 12 seconds. Activates a 1,200ms extended invulnerability window — more than double a normal

dodge roll. Deals a small 0.5× ATK hit on activation. Ideal for surviving boss enrage phases in Phase 3 where dodging alone isn't enough.

▸ Time Shift (Unlocks at Level 25)

Category: UTILITY | Energy Cost: 40 | Cooldown: 15 seconds . Disrupts the boss's internal timing, adding 5,000ms to their next action countdown.

Effectively stuns the boss mid-attack. The most powerful crowd-control ability in the game — and the most expensive. Reserved for players who have mastered Energy management.

COOLDOWN SYSTEM:

Every skill has an independent cooldown tracked in milliseconds. The SkillSystem.tickCooldowns() function reduces all active cooldowns in sync with the battle's 16ms game loop tick. The UI displays a live countdown on each skill button so players can plan their next move precisely.

STRATEGIC DEPTH:

Skills are not spammable. The combination of Energy costs and individual cooldowns means a player must choose their moment: burn Energy Burst through a boss shield now, or save it for Phase 3? Use Time Shift to survive an enrage, or hold it for a combo extension? These decisions — made in real-time under pressure — are what elevate Hidden Realms beyond a simple tap game.

Progression System

The Progression System is the long-term backbone of Hidden Realms — the reason every battle fought, every treasure collected, and every kilometre walked actually means something. Every action feeds into a single permanent growth curve that transforms your character from a Level 1 Wanderer into a Level 50 Realm Master.

HOW WE IMPLEMENTED IT

All character progression is handled by the PlayerRepository, a data layer component that manages the player's persistent state using Room SQLite database. Every XP gain — whether from collecting a treasure node, defeating a boss, or walking a distance milestone — routes through a single addXp() function. This function runs a while loop that compares your current XP against the threshold for the next level, granting as many level-ups as your XP total covers in one atomic database write. No level-up is ever lost.

THE XP FORMULA:

Required XP = 100 × (1.2 ^ currentLevel)

This is an exponential curve implemented using Kotlin's math.pow() function:

▸ Level 2 requires 100 XP

▸ Level 5 requires 207 XP

▸ Level 10 requires 516 XP

▸ Level 20 requires 3,833 XP

▸ Level 50 requires 910,043 XP

Early levels are fast and rewarding. The endgame is a real grind — by design.

STAT GROWTH PER LEVEL:

Every single level grants:

▸ +5 Max HP — your health pool grows steadily every level

▸ +1 ATK — attack power increases every level

▸ +1 Skill Point — spend these to unlock new active skills

Every 5 levels (5, 10, 15 ... 50) grants bonus:

▸ +2 ATK bonus — a noticeable power spike at milestone levels

▸ +1 DEF — defence stat increases, reducing boss damage taken

Every 10 levels (10, 20, 30, 40, 50) grants:

▸ +1 Speed — affects dodge window timing in combat

RANK TITLES — THE 5 MILESTONES:

As your level grows, your Rank Title on the Profile screen automatically updates:

Level 1–10 → Wanderer "A curious soul taking their first steps into the Hidden Realms."

Level 11–20 → Explorer "A seasoned adventurer uncovering secrets."

Level 21–30 → Hunter "A skilled pursuer of treasures and vanquisher of foes."

Level 31–40 → Guardian "A steadfast protector of the balanced realms."

Level 41–50 → Realm Master "An absolute legend across all dimensions."

Each rank is stored as a string in the PlayerEntity Room table and rendered with its own colour on the Profile screen.

BONUS XP SOURCES — EXPLORATION REWARDS:

Hidden Realms rewards players who actually explore. Beyond battles, XP is earned through:

▸ Distance Milestones — Every 500 metres walked (tracked by the GPS system) awards 25 XP. Walk 5 km in a day and earn a meaningful bonus.

▸ Portal Battles — Higher rarity portals award more base XP: Common (50–120 XP), Rare (150–280 XP), Epic (350–600 XP), Legendary (800–1,500 XP)

▸ Treasure Nodes — Instant XP on collection, scaled to node rarity.

▸ AR Ambient Orbs — XP from ambient treasure orbs collected while the AR camera is open.

BOSS SCALING:

To keep the game challenging as you level up, all bosses scale dynamically with your level:

Scaled Boss HP = baseHP + (playerLevel × 30)

Scaled Boss ATK = baseATK + (playerLevel × 3)

A Level 1 boss that was manageable at Level 5 becomes a genuine threat again when you face it at Level 30. The world scales with you.

Inventory and Gear

The Inventory and Gear system gives every piece of loot a purpose. Every battle won, every treasure node collected, and every portal closed can drop an item. What you collect and what you equip directly changes your combat capabilities — this is a real RPG stat system, not decoration.

HOW WE IMPLEMENTED IT

Loot generation is handled by the LootGenerator — a singleton object that takes the source node's rarity tier and generates a LootDrop by sampling from a tiered item pool. Each rarity has its own dedicated pool of possible items:

▸ COMMON Pool → Health Potions, Gold Coins, Gem Shards

▸ RARE Pool → Gem Shards, Skeleton Keys, XP Boosters

▸ EPIC Pool → Arcane Keys, Ancient Scrolls, XP Boosters

▸ LEGENDARY Pool → Dragon Eggs, Dragon Seals, Ancient Scrolls

The loot drop (item type + rarity + XP amount) is written atomically to the Room inventory table. Your collected items persist permanently on-device — no internet required.

XP REWARD PER DROP (by node rarity):

Common nodes → 50 – 120 XP

Rare nodes → 150 – 280 XP

Epic nodes → 350 – 600 XP

Legendary nodes → 800 – 1,500 XP

The exact XP value within each range is randomised on drop, keeping each collection feel slightly different.

EQUIPMENT SLOTS:

The Inventory screen has four distinct equipment slots that accept different item categories:

▸ Weapon Slot — Equipped weapons increase your ATK stat directly, amplifying all combat damage calculations.

▸ Armor Slot — Equipped armor boosts your DEF stat and adds to your Max HP pool, increasing survivability.

▸ Relic Slot — Passive combat relics apply ongoing bonuses (e.g., faster energy regeneration, increased crit chance).

▸ Artifact Slot — Utility artifacts provide special effects (e.g., extra potion charges, extended dodge invulnerability frames).

RARITY STAT MULTIPLIERS:

The same item type at different rarities is a meaningfully different power level:

Common ×1.0 — Standard baseline. Gets you started.

Rare ×1.5 — Noticeably stronger. Worth swapping in.

Epic ×2.0 — Game-changing upgrade. Redefines your build.

Legendary ×3.0 — Rare, dramatic power spikes. Changes how you play.

GEM SHARD FORGE — THE DETERMINISTIC UPGRADE PATH:

RNG can be frustrating. So we built a guaranteed fallback. Gem Shards are a special currency item that drops from multiple rarity tiers. Collect 10 Gem Shards and bring them to the Forge (accessed from the Inventory screen) to craft a guaranteed Rare item — no luck required.

This gives players a deterministic progression path. If random drops are being unkind, farming Gem Shards from regular treasure nodes will always yield a meaningful upgrade after enough effort.