TOUCHCRAFT 2D (HP Prime G2)
Detailed README for current build

Program file:
- touch_minecraft2d_new.hpprgm

Exported entry point:
- TOUCHMC2DNEW()

Version context:
- This README describes the current code in touch_minecraft2d_new.hpprgm exactly as implemented now.

==================================================
1) GAME OVERVIEW
==================================================

TouchCraft 2D is a side-view sandbox game for HP Prime G2 with:
- Touchscreen movement/build controls
- Independent D-pad crosshair controls
- Chunk-buffered terrain streaming
- 3 save slots with world names and seeds
- In-app virtual keyboard for world creation
- Title screen, world menu, create menu, pause menu

The game area is the top part of the screen and touch controls are always visible at the bottom.

==================================================
2) SCREEN AND WORLD SETTINGS
==================================================

Display:
- Full screen: 320 x 240
- Gameplay viewport: 320 x 140 (top)
- Control panel: y = 140..239 (bottom)

Tile and camera:
- Tile size: 20 px (unchanged)
- Visible world area: 16 columns x 7 rows
- Crosshair bounds: x 0..319, y 0..139

World model:
- World height: 32 tiles
- Chunk width: 16 tiles
- Active chunk radius: 2 (5 chunks active for interaction)
- Preload chunk radius: 3 (7 chunks buffered)
- Buffer width: 112 columns (7 * 16)

==================================================
3) CONTROLS
==================================================

A) Touch controls (in-game)
- L button: hold to move left
- R button: hold to move right
- JUMP button: tap/hold to jump (edge-triggered)
- BLOCK button: tap to cycle selected block type
- BREAK button: tap to remove targeted block
- PLACE button: tap to place selected block at target
- II button (top-right): open pause screen

B) Hardware key controls (in-game)
- Documentation format below uses key name + numeric key code.
- Right (D-pad), key code 8: move crosshair right
- Left (D-pad), key code 7: move crosshair left
- Up (D-pad), key code 2: move crosshair up
- Down (D-pad), key code 12: move crosshair down
- ENTER (jump), key code 30: jump (same behavior as touch JUMP button)
- Key code 49: immediate program exit

Important behavior:
- D-pad keys move crosshair only.
- Touch move buttons move the player.
- Crosshair and player are independent.

C) Menu controls
- Menus are touch-driven.
- Menus use touch-release arming logic to reduce accidental clicks from previous screens.

==================================================
4) GAMEPLAY RULES
==================================================

Physics and movement:
- Gravity, jump velocity, and capped fall speed are enabled.
- AABB collision is used for block collision.
- Horizontal and vertical movement are stepped for stability.
- If overlap is detected after movement, safety rollback restores last safe position.

Crosshair targeting:
- Crosshair points to a tile in world space using camera + crosshair pixel position.
- BREAK/PLACE acts on that tile.

Place/break limits:
- Edits are allowed only within the currently active chunk window.
- Cannot place blocks inside the player AABB.
- Breaking sets tile to air (0).

Player constraints:
- Player is clamped to x >= 1 + halfWidth.
- Prevents invalid negative-side indexing and chunk edge issues.

==================================================
5) BLOCK TYPES
==================================================

Palette order (cycled by BLOCK button):
1 = DIRT
2 = GRASS
3 = STONE
4 = DARK
5 = WOOD
6 = SAND

Terrain uses these IDs directly.

==================================================
6) MENUS AND FLOW
==================================================

Startup flow:
1. Title screen
2. World select menu
3. Load existing slot OR create new world in slot
4. Enter gameplay

Title screen buttons:
- PLAY: opens world selection
- DELETE: opens delete slot picker
- EXIT: exits program

World selection menu:
- SLOT 1/2/3 selector
- LOAD: loads selected slot if used
- CREATE: opens world creation for selected slot
- BACK: returns to title

World creation menu:
- Name field (uses in-app alphabet keyboard)
- Seed field (uses in-app numeric keyboard)
- CREATE: builds world and saves to selected slot
- BACK: returns to world menu

Pause menu:
- RESUME: return to gameplay
- TITLE: auto-saves current slot, then returns to title/world flow

Note:
- Pause menu no longer has a separate SAVE button.
- Exiting to title from pause always auto-saves to the active slot.

==================================================
7) SAVE / LOAD SYSTEM
==================================================

Slot count:
- 3 slots total

Storage key names:
- TM2D_SLOT1
- TM2D_SLOT2
- TM2D_SLOT3

Saved data payload format:
{1, world, baseCol, px, py, vx, vy, sel, crossX, crossY, activeCenterChunk, preloadCenterChunk, facing, seed, worldName}

Field notes:
- world: current buffer matrix
- baseCol: world column represented by buffer column 1
- px/py/vx/vy: player state
- sel: selected palette index
- crossX/crossY: crosshair pixel position in gameplay viewport
- activeCenterChunk/preloadCenterChunk: streaming state
- facing: player facing direction
- seed: world seed used by procedural terrain
- worldName: user world name

Compatibility behavior:
- Loader accepts older payloads with fewer fields and upgrades defaults when needed.

Delete behavior:
- Delete removes the slot app variable via DelAVars.

==================================================
8) WORLD GENERATION
==================================================

Generation characteristics:
- Side-view layered terrain using seeded sine-based height variation
- Top layer is mostly grass, with occasional sand biomes
- Subsurface uses dirt/sand transitions and deeper stone/dark mix
- Bottom row forced to stone

Border behavior:
- For world x <= 1, terrain is forced solid DARK (hard left border)

Streaming behavior:
- Buffer shifts by chunk steps as player progresses
- Outside buffer, terrain is sampled procedurally from seed
- This gives effectively unlimited terrain in +X direction while keeping a hard left boundary

Spawn behavior:
- Spawn is generated near preload center
- Spawn clearance removes a small 3x4 air pocket above ground
- Spawn is corrected upward if collision is detected

==================================================
9) VIRTUAL KEYBOARD (WORLD NAME / SEED)
==================================================

Name keyboard:
- Uppercase letters A-Z + SPACE
- Buttons: OK, CANCEL, CLEAR

Seed keyboard:
- Digits 0-9 + minus
- Buttons: OK, CANCEL, CLEAR, RAND
- RAND clears the seed text; create logic then uses random seed when empty/invalid

Seed parsing:
- Seed text is evaluated and integer-converted (EXPR then IP)
- Invalid input falls back to random seed

Current limitation:
- No single-character backspace key; use CLEAR to reset field.

==================================================
10) PERFORMANCE ARCHITECTURE
==================================================

Current anti-lag optimizations included:
- Row run-length terrain rendering (batches same-tile runs into fewer RECT calls)
- Fast renderer path when visible columns are fully inside buffer
- Fallback renderer path only when camera is near buffer edges
- Integer-pixel camera projection to reduce visual seams
- EnsureBuffer only called when required range leaves current buffer
- Direct hot-loop collision checks (reduced function overhead)
- Partial UI redraw strategy for static control elements

Debug logging:
- dbgMoveLog variable exists and defaults to 0
- Keep it 0 for normal gameplay performance

==================================================
11) TROUBLESHOOTING
==================================================

If game feels laggy:
- Make sure debug logging is off (dbgMoveLog = 0)
- Keep interaction inside active visible area when possible
- Use latest touch_minecraft2d_new.hpprgm (older files in folder are legacy)

If save/load seems wrong:
- Confirm slot actually contains data (USED/EMPTY indicators)
- Loading requires an existing slot
- Creating in a slot overwrites that slot with a new world

If world name/seed input is confusing:
- Use in-app keyboard only
- OK confirms
- CANCEL returns original field
- CLEAR wipes full field

If pause behavior seems different than older builds:
- TITLE from pause now auto-saves and returns to title flow
- Manual pause-save button was intentionally removed

==================================================
12) FILES IN THIS FOLDER (RELEVANT)
==================================================

Primary game file:
- touch_minecraft2d_new.hpprgm

Other files are older experiments/variants and not the current main build.

==================================================
13) QUICK START
==================================================

1. Transfer/import touch_minecraft2d_new.hpprgm to HP Prime.
2. Run TOUCHMC2DNEW().
3. On title, tap PLAY.
4. Pick a slot, then LOAD or CREATE.
5. In-game, use touch controls for movement/build and D-pad keys for crosshair.
6. Use pause II button, then TITLE to auto-save and return to title when done.

End of README.
