phantasia

Phantasia - 2D SDL3 RPG prototype.
git clone git://git.beep.wimdupont.com/phantasia.git
Log | Files | Refs | README | LICENSE

README.adoc (4030B)

      1 = phantasia
      2 
      3 2D SDL3 RPG prototype.
      4 
      5 == Direction
      6 
      7 * FFVI-like top-down movement and camera feel.
      8 * Visible enemies instead of random encounters.
      9 * FFX-inspired CTB combat whose turn order responds to agility and action speed.
     10 * Loot-heavy progression with meaningful build choices.
     11 * Optional, discoverable story that does not interrupt play.
     12 * A small set of clear rules that gains depth through interaction, like chess.
     13 
     14 == Principles
     15 
     16 Phantasia's details may change while these principles remain stable:
     17 
     18 * Put performance, simplicity, and the core gameplay loop first.
     19 * Prefer the smallest clear implementation. Remove, reuse, or combine before
     20   adding abstractions, special cases, files, or substantial code.
     21 * Build foundations that expand through typed data and configuration. New
     22   content should not require initialization or rendering special cases.
     23 * Treat file count and lines of code as costs, but never trade clarity or
     24   correctness for a smaller number.
     25 * Verify changes carefully and preserve existing behavior deliberately.
     26 * Keep compile-time settings visible through the suckless
     27   `config.def.h`/`config.h` model.
     28 
     29 == Architecture
     30 
     31 Phantasia is a game, not a general-purpose engine product. Its systems are
     32 nevertheless engine-like: they operate on entities, items, interactions, area
     33 markers, and caller-supplied catalogs rather than named game content. Here,
     34 "engine" means the reusable internal layer, not a separately packaged framework
     35 or a promise of API compatibility.
     36 
     37 `src/engine` contains reusable systems and must never include `game/*`.
     38 `src/game` owns Phantasia's content, menus and overlays, and application startup;
     39 it may depend on the engine. Generic code belongs in the engine whenever it can
     40 operate entirely on engine types and supplied data.
     41 
     42 Core logic remains headless-testable. SDL rendering is an optional engine layer,
     43 while game-specific presentation and application orchestration stay outside the
     44 simulation.
     45 
     46 For the current implementation, start with `src/engine/*.h` for the engine's
     47 public data types and operations, `src/game/content.c` for a concrete game setup,
     48 and `src/tests/` for headless and SDL integration examples. Source remains
     49 authoritative for exact systems, types, and content as they evolve.
     50 
     51 == Content and configuration
     52 
     53 The first build copies tracked defaults from `config.def.h` to ignored local
     54 `config.h`. Later builds preserve `config.h`, which is the sole source of active
     55 settings. A configuration API version rejects stale files so missing values are
     56 never replaced by silent core-code fallbacks.
     57 
     58 Configuration owns adjustable settings; `game/content` owns typed game data.
     59 Maps own placement, while content assigns semantics to their markers. Adding an
     60 instance should normally change only a map; adding content should change the
     61 catalog and map rather than engine code.
     62 
     63 Vendored media is grouped by role under `assets/vendor/graphics` and
     64 `assets/vendor/audio`. Each upstream asset directory keeps its own source and
     65 license record.
     66 
     67 == Build
     68 
     69 [source,sh]
     70 ----
     71 make
     72 ----
     73 
     74 Without SDL3, build and run the headless smoke suite:
     75 
     76 [source,sh]
     77 ----
     78 make smoke
     79 ----
     80 
     81 Exercise SDL rendering in a headless environment:
     82 
     83 [source,sh]
     84 ----
     85 make render-smoke
     86 ----
     87 
     88 With SDL3 available:
     89 
     90 [source,sh]
     91 ----
     92 ./bin/phantasia
     93 man ./phantasia.6
     94 ----
     95 
     96 At startup, choose Continue to restore the autosave or New Game to replace it.
     97 The game saves atomically on area transitions and clean exit. The save path is
     98 configured by `PH_SAVE_PATH`; static map tiles are reloaded from game data while
     99 player progression and each visited area's mutable actors and ground items are
    100 persisted.
    101 Starting combat creates a stable pre-combat checkpoint. Exiting during combat
    102 does not overwrite it with a partial battle; victory saves the finalized result.
    103 
    104 == Maps
    105 
    106 Sources live in `data/maps/*.txt`. `make` compiles them with `bin/ph-mapc` into
    107 `obj/maps/*.phmap`. Tile and marker meanings are typed data in `game/content.c`,
    108 which is the authoritative reference as maps evolve.