[简体中文](README.zh-CN.md) · English # Mario: first-level side-scrolling GUI example A Windows x64 platform game built with this project's custom C compiler, runtime, and PE linker. Inspired by the above-ground route of Super Mario Bros. World 1-1, it includes a 216-column level, scrolling camera, bricks, question blocks, coins, mushroom growth, Goombas, Koopas and shells, pipes, gaps, stairs, a flagpole, and a castle. Characters, terrain, and backgrounds are drawn with C and GDI; text uses a system font. No bundled images, ROM, or game engine is required. This educational gameplay recreation is not a pixel-exact reproduction of the original layout, graphics, or physics. It omits underground bonus rooms, audio, fireballs, and the original completion animation. Reaching the flagpole completes the level. ## Build and run Run from the release root in **Windows PowerShell 5.1**. Skip the first step if tools are already built. `build-all.ps1 -All` already builds this example, so it can be run directly. Default mode and `-Full` do not build it; see [Build modes](../../../README.md#build-modes). ```powershell # Run first if tools are not built; skip if the final compiler and linker already exist. & './build-all.ps1' if (!$?) { throw 'Toolchain build failed' } & './src/examples/mario/build.ps1' if (!$?) { throw 'Game build failed' } & './src/examples/mario/build/mario.exe' ``` You can also double-click the generated `build/mario.exe`. Only a Windows GUI executable is produced; startup does not allocate a console. The client area is 960×544 and the interface is in English. | Key | Action | | --- | --- | | Left/right arrows or A/D | Move | | Space, up arrow, or W | Jump; hold for a higher jump, release to shorten it | | Shift | Run faster; combine with movement and jumping | | P | Pause/resume | | R | Restart the entire game | | Esc or close window | Quit | Normal play pauses on loss of focus; press P to resume. You start with 3 lives and earn one for every 100 coins. Mushrooms make the player larger and able to break bricks. A large player shrinks on damage and is briefly invulnerable; a small player taking damage, falling into a gap, or running out of time loses a life. Stomping enemies awards points and bounces the player. Stomping a Koopa turns it into a shell; stationary shells can be kicked and moving shells stopped by stomping. Moving shells bounce, defeat enemies, and can hurt the player. A stationary shell returns to a Koopa after about 10 seconds of updates near the player. Passing column 104 sets a checkpoint. If lives remain, death resets terrain, enemies, and time while preserving score and coins. Press R after completion or game over to restart. To use custom toolchain or output directories: ```powershell & './src/examples/mario/build.ps1' ` -BuildDirectory './work/walkthrough' ` -OutputDirectory './work/mario' if (!$?) { throw 'Game build failed' } & './work/mario/mario.exe' ``` `-BuildDirectory` must contain `host/c1-stage2.exe` and a `link-stage2.exe` supporting `--subsystem windows`. Close any running game at the same output path before rebuilding. ## Implementation and build provenance `mario.c` contains normal gameplay; `demo.h` contains automated input and the full-scene demo test. Source is compiled in C99 mode and explicitly declares the required Windows x64 ABI without Windows SDK, windows.h, or import-library dependencies. Logic uses 1/16-pixel fixed-point values and 60 fixed updates per second. A Win32 timer drives the message loop; accumulated time compensates for short delays. Collisions use small pixel steps, and GDI memory bitmaps plus BitBlt provide double buffering. `build.ps1` compiles game and argument-enabled runtime objects with the custom compiler, then links them with entry `__c1_start` and subsystem `windows`. Imports are limited to Windows KERNEL32, USER32, and GDI32. PowerShell handles only text and tool calls; all objects and EXEs are generated by custom tools. Wrapper sources, objects, and the EXE default to this example's `build/`. Root `clean-all.ps1` removes that directory in full, including test reports. Manage custom `-OutputDirectory` locations yourself. ## Automated tests ```powershell & './src/examples/mario/test.ps1' # For a custom output location: # & './src/examples/mario/test.ps1' -Executable './work/mario/mario.exe' ``` Build the example first. The script verifies the PE GUI subsystem and runs three modes of the same EXE, judging success by exit code. The first two have 30-second timeouts; the demo test has 120 seconds. No mode of root `build-all.ps1` runs these tests. - `--self-test`: Win64 layouts, movement/collisions, items, damage, lives, timing, pause, the endpoint, and shell behavior. Includes an input-driven full-level terrain traversal with enemies isolated; separate scenes test enemy interactions. - `--smoke-test`: creates a hidden window, checks keys, timer events, pause/restart, and uses WM_PRINTCLIENT to draw a memory bitmap and check pixels. An optional BMP path saves that frame; save failure returns nonzero. - `--demo-test`: runs the automated player without a window, preserving all enemies and items, with the same pass conditions as the visible demo below. The script supplies `gameplay-test.txt` beside the EXE as a report path. The program records progress/results if it can open the file; report-write failure alone does not fail the test. Tool interfaces are in [USAGE.md](../../../USAGE.md). ### Watch the full-scene demo ```powershell & './src/examples/mario/build/mario.exe' --terrain-test-visible ``` The built-in player starts about 3 seconds after the window appears. Passing requires reaching the flagpole, hitting at least two reward blocks, obtaining coins, collecting loose scene coins, picking up a mushroom, stomping a Goomba, stomping a Koopa, and kicking a shell. The controller simulates future inputs in copied state, then supplies its chosen keys to normal gameplay updates. The map, enemies, timing, damage, and physics match manual play. Planning can reduce rendering frame rate. The display shows interaction counts and final PASS/FAIL. Death, reaching the endpoint without meeting conditions, or hitting the 6,000-update limit fails. Demo mode does not pause on focus loss; use P to pause/resume or Esc to quit. The result remains on screen rather than closing automatically.