GnollHack

Guidelines for working on the C# .NET MAUI mobile and desktop frontend client (GnollHackM), SkiaSharp game rendering, XAML page layouts, FMOD audio integration, and the P/Invoke native bridge.

Guidance on modifying the GnollHack C core game logic, headers, windowing callbacks, sound/animation definitions, and dungeon data files. Covers K&R coding style, macro idioms, and key data structures.

Guidelines and patterns for converting non-portable C Bitfield macros into platform-portable explicit bitmask flags to fix cross-platform save game compatibility.

Instructions on how to use wizard mode (debug mode), decipher panic logs, test specific levels/monsters, and run the MAUI frontend locally.

Guide on building GnollHack native C libraries, processing assets with makedefs/levcomp/dgncomp/dlb, packaging nhdat, and compiling the C# .NET MAUI frontend for Android, iOS, and Windows.

Best practices for AI agents documenting the GnollHack C# .NET MAUI codebase. Covers XML doc comments, inline comments, P/Invoke documentation, and Microsoft-standard documentation patterns for the game's frontend, native bridge, and UI code.

Patterns for adding monsters, objects, and artifacts to GnollHack. Covers MON/WEAPON/ARMOR/A macro syntax, attack tuples, monster and object flags, the auto-generated headers (pm.h, onames.h), soundset and animation assignments, and the makedefs rebuild pipeline.

Best practices for AI agents documenting the GnollHack C codebase. Covers file headers, function documentation, inline comments, macro explanations, and strategies for making legacy NetHack-derived C code understandable to modern developers.

Patterns for converting K&R C function definitions to C99 ANSI-style prototypes, removing STATIC_DCL/STATIC_OVL macros, converting VA_DECL variadic functions, removing register keywords, and eliminating parameter type macros (BOOLEAN_P, CHAR_P, etc.).

Guide to modernizing GnollHack header infrastructure for C99, covering tradstdc.h simplification, extern.h prototype conversion, removal of compatibility macros (FDECL, NDECL, VDECL, BOOLEAN_P, CHAR_P), and cleanup of dead platform-specific code.

Master reference for migrating the GnollHack C codebase from K&R C to C99, covering conversion phases, ordering dependencies, rules for what changes and what stays, per-file workflow, verification steps, and coordination between header and source file modernization.

Guide to understanding and modifying GnollHack game data files including level descriptions (.des), dungeon definitions, text databases, and the data compilation pipeline from source text to nhdat archive.

Guide to the GnollHack glyph-to-tile rendering pipeline. Covers glyph numbering, the multi-layer display system, the LayerInfo struct, tile sheet atlases, the Glyph2Tile mapping, double-buffered MapData, and how SkiaSharp renders tiles on the C# side.

Multi-threaded programming patterns in GnollHack's .NET MAUI frontend. Covers thread architecture, lock strategies (Monitor.TryEnter, lock, Interlocked), the IThreadSafeView pattern, ConcurrentQueue-based inter-thread communication, and platform-specific GPU rendering thread behavior.

Guidelines on modifying the save/load system, which is complex and heavily relies on struct alignment and file I/O operations that can easily break cross-platform saves.