Sandbox

Sandbox

Overview

The Sandbox is a dedicated developer testing environment for the game's Item / Inventory system and closely related integrations.

It provides quick access to items, a shopkeeper, grapple platforms, and selectable enemies, allowing developers to reproduce test conditions without progressing through normal gameplay.

During Sprint 3, its role expanded to support regression testing of inventory UI, item effects, resource handling, and entity cleanup.

Version scope: This document describes the implementation inspected on feat/advanced-inventory-system at commit 2196c82d. Confirm the branch being tested before applying these instructions to main.

Purpose

The sandbox provides a central environment to:

• Obtain implemented items quickly.
• Test inventory selection, item use, and UI updates.
• Observe health and movement changes.
• Test shop interactions and purchases.
• Reproduce projectile, status-effect, and enemy interactions.
• Verify fixes and investigate cross-team integration issues.

Accessing the Sandbox

1. Launch the game from the branch being tested.
2. Select Sandbox from the Main Menu.
3. Use the sandbox's exit control to return to the main menu.

The sandbox uses its own screen and service setup while reusing the project's player, inventory, item, physics, and UI systems.

Sandbox Layout

The environment contains:

• A desert background and a continuous ground platform.
• A player spawn location.
• A shopkeeper near the player's starting position.
• Three raised grapple platforms.
• A row of labelled item pickups.
• A clickable enemy-spawner NPC to the left of the player.
• Player health, gold, and sandbox-enabled health and speed text.

Items appear from left to right in ascending ItemType.getId() order. Each world pickup is created with a quantity of 99; inventory capacity and stacking rules still govern pickup behaviour.

Available Items

ID	Item	Main testing purpose
1	Standard Arrow	Ammunition, selection, and projectile interactions
2	Rope Arrow	Grapple connection and release
3	Health Potion	Healing and health UI updates
4	Fire Arrow	Projectile damage and burning effects
5	Ice Arrow	Projectile damage and slowing effects
8	Speed Potion	Temporary movement changes
9	Poison Potion	Thrown-flask interactions and poison effects

The item row is generated from ItemType.values(), rather than a separate hard-coded catalogue. New types also require compatible factory implementations and available resources.

Sword and spear are not part of the inspected item catalogue.

Screenshots

The following screenshots are retained from the earlier Wiki version as historical references. They should be replaced with current captures showing the shopkeeper, grapple platforms, enemy-spawner panel, and status text.

Earlier sandbox overview

Earlier item layout

Item Testing

1. Enter the sandbox and locate the labelled item.
2. Pick it up and check its icon, quantity, and inventory position.
3. Select and use it through the current gameplay controls.
4. Observe its effect, ammunition or quantity changes, and UI updates.
5. Repeat the interaction to check for stale selection, duplicated UI, or inconsistent behaviour.
6. Record the branch, item, steps, expected result, and actual result when reporting a defect.

Use the raised platforms for rope-arrow testing and spawned enemies for projectile and status-effect testing.

The health text displays current and maximum health. The speed text displays the absolute horizontal physics velocity, rounded to two decimal places; it does not display total movement speed.

Shop Testing

The sandbox includes a shopkeeper for repeatable purchase testing.

Player gold is set to 999,999. When it changes, the sandbox schedules restoration through an application callback. This is a developer convenience and does not represent normal-game economy behaviour.

Suggested checks:

1. Open the shop through its normal interaction.
2. Purchase an available item.
3. Check that the inventory receives the correct item and quantity.
4. Check that shop and inventory UI update consistently.
5. Confirm that sandbox gold is restored after the callback.
6. Repeat purchases and inspect capacity or stacking behaviour.

Use separate automated or normal-game tests for insufficient funds, realistic prices, and gold boundary conditions.

Enemy and Status-Effect Testing

Click the enemy-spawner NPC to open its selection panel.

1. Choose Skeleton Warrior or Skeleton Archer.
2. Leave Active checked for the active enemy variant, or uncheck it for the passive variant.
3. Select Spawn.
4. Test the required item or projectile interaction.
5. Spawn another enemy when a fresh target is needed.

Only one spawner-managed enemy is retained at a time. Generating another removes the previous one.

Opening the panel releases held gameplay input and pauses entity updates. Closing it restores the previous pause state.

The two modes allow comparison of item interactions against a passive target and an active enemy. They do not guarantee that every combat interaction is correct.

Sprint 3 Regression Checklist

The sandbox supports manual checks related to the Sprint 3 refinement work.

Area	Suggested check
Inventory selection	Move between occupied and empty slots; inspect highlighting and selected-item state
UI refresh	Pick up, use, and purchase items repeatedly; check for duplicated or stale UI
Rope arrow	Connect to platforms, release, and repeat; check rope and player state
Consumables	Check healing, temporary speed changes, poison interactions, and quantity updates
Arrows	Check selection, ammunition changes, and fire or ice effects
Enemy replacement	Switch enemy types and modes; check that the previous enemy is removed
Shop	Repeat purchases; inspect inventory updates and sandbox gold restoration
Screen lifecycle	Exit and re-enter; inspect missing textures, duplicate UI, and leftover entities

Area transitions require additional testing in normal gameplay. Re-entering the sandbox starts a new screen and does not establish that the player's inventory or world items behave correctly across normal level transitions.

Automated Tests and Resource Lifecycle

Manual observation is complemented by automated tests in the repository:

• SandboxGameAreaTest: required platform and player-HUD texture preloads.
• SandboxLifecycleTest: item ordering, loaded icons and physics bodies, active/passive enemy replacement, deferred gold restoration, and area cleanup.
• SandboxGameScreenTest: screen creation, rendering invocation, exit navigation, and disposal of screen services.
• PlayerStatsDisplayTest: focused coverage for the shared player-stat display.

The area loads required textures, atlases, and sounds before spawning its content. Its disposal method unloads area-owned resources. Screen disposal clears registered entities and services and disposes rendering, resource, and physics infrastructure.

Area-level disposal and full-screen disposal have different responsibilities: shared area cleanup preserves the player for transitions, while leaving the sandbox screen disposes the screen's registered entities.

These test descriptions identify existing coverage. They are not a statement that the tests passed during this documentation update.

Cross-Team Usage

Player, UI, combat, and economy developers can use the sandbox when their work interacts with Item / Inventory.

A useful bug report should include:

• Branch or commit.
• Item and enemy type, where relevant.
• Active/passive setting.
• Reproduction steps.
• Expected and actual behaviour.
• Screenshot or application log where useful.

This gives teams a shared starting point for reproducing integration failures.

Scope

The sandbox is focused on inventory items and the systems needed to test them.

Shopkeepers, selectable enemies, grapple platforms, and player-stat text are included because they support those tests.

It is not intended to reproduce full level progression, every enemy type, complete economy balancing, unrelated hazards, or narrative sequences. Additions should have a clear testing or debugging purpose.

Design Considerations

Deterministic Item Placement

Numeric IDs determine item order, making the layout predictable as the catalogue changes.

Reuse of Gameplay Systems

Using existing factories and components helps expose integration problems that isolated item tests may miss.

Resource Ownership and Cleanup

Resource loading and disposal must remain consistent with the current asset paths and lifecycle rules. Updates should be checked for missing assets, stale entities, duplicate UI, and incorrect texture ownership.

Maintainability

Keep item generation connected to the current catalogue and update documentation when controls, supported items, or test facilities change.

Development Workflow

Implementation → Automated Checks → Sandbox Testing → Bug Investigation / Collaboration → Regression Checks → Review → Integration

Use automated tests for deterministic logic and the sandbox for rendering, input, physics, and multi-system observations. Include normal-game testing when a change involves level progression or transitions.

Limitations

• The sandbox provides test conditions; it does not prove that item effects or integrations work correctly.
• Rendering and layout still need direct in-game observation.
• High, replenished gold is unsuitable for normal economy validation.
• Only the two listed enemy types are available through the spawner.
• Sandbox exit/re-entry does not replace normal level-transition tests.
• Features and assets may differ between the feature branch and main.

Future Development

Extend the sandbox only where a new item or integration requires a repeatable test condition. Keep this page's item list, screenshots, controls, and version scope aligned with the implementation.

Related Evidence

• Sandbox implementation — PR #99
• Sprint 3 refinement and testing — Task #187
• Item / Inventory refinement — PR #189
• Asset and code refinement — PR #193

These links document development evidence. Check each PR's status before describing its changes as integrated into main.