canary/docs/maps
Eduardo Dantas e99d283ebf
perf: improve Canary startup loading performance (#3968)
Improve Canary startup performance by reducing Lua/script loading cost, optimizing map parsing and cache construction, and lowering repeated lookup/allocation work during monster spawn startup.

Measured impact:
- Loaded modules and scripts wall time improved from about 54s to 1.516s best observed, with 2.997s in the latest captured run, about 94% to 97% less wall time.
- Scripts::loadScripts dropped from 17.60% to 9.31% to 15.00% across later captures.
- luaL_loadfile dropped from a dominant original hotspot to 1.60% to 2.80%.
- getLuaBytecodeCacheEntry appeared at only about 0.49% to 0.51%, showing cache lookup is cheap compared to the old file-load path.
- CanaryServer::loadMaps dropped from 65.59% after the Lua improvements to 57.68% in the latest capture.
- IOMap::parseTileArea dropped from 59.58% to 53.87%.
- MapCache::setBasicTile dropped from 24.96% to 20.50%.
- phmap::try_emplace for cached basic tiles dropped from 7.25% to 0.99%.
- MapSector::createFloor dropped from 7.17% to 5.76%.
- SpawnMonster::startup dropped from 11.74% to 9.56%.
- SpawnMonster::spawnMonster dropped from 10.64% to 9.13%.

Main changes:
- Add Windows RelWithDebInfo compiler and linker settings for useful release profiling symbols.
- Add Lua startup telemetry options and bytecode cache configuration.
- Make the Lua debug hook configurable so release profiling can avoid unnecessary hook overhead.
- Improve Lua script loading by reducing filesystem metadata work, using bytecode cache entries, loading from memory when possible, and supporting packed cache data.
- Add detailed startup timing logs for modules and datapack directories.
- Add map-load reservations after reading the map header, including cache and container reservations based on map dimensions.
- Add simple-tile and cache fast paths for common map-loading tile shapes.
- Reduce shared pointer churn in the map cache path by using raw cache pointers internally where cache ownership is already guaranteed.
- Reduce repeated sector and floor lookup work while parsing map tiles.
- Improve zone indexing and copy behavior to avoid unnecessary set copies in spawn and tile insertion paths.
- Optimize monster spawn startup by reusing resolved tile data and avoiding redundant lookups while preserving spawn behavior.
- Move broad headers into pch.hpp where appropriate to keep benefiting from the precompiled header setup.
- Add docs/maps/startup-loading-performance.md with profiling notes, decisions, results, and follow-up areas.
- Add tests for map-download helpers and weighted monster spawn selection.
- Add ignore rules for the Lua bytecode cache directory.

Notes:
- The profile captures are sampling profiles, so percentages represent sampled CPU share, not direct wall-clock speedup.
- The latest 2.997s run appears to include local machine variance, but it remains far below the original 54s baseline.
- Map loading is now the main remaining startup hotspot.
- No behavior, map semantics, or spawn semantics are intended to change.
2026-05-22 16:58:43 -03:00
..
startup-loading-performance.md perf: improve Canary startup loading performance (#3968) 2026-05-22 16:58:43 -03:00