HMP Foundations

HMP Foundations is the cohesive, versioned stack of common resources for HogwartsMP servers. Its resources share the hmp- namespace, are designed and tested together, and remain independently adoptable through normal resource dependencies.

This repository is separate from the MafiaHub C++ Framework used to build HogwartsMP. Foundations is the server scripting layer built on top of that runtime.

Installing a server? Start with INSTALL.md. It covers the directory layout, database creation and credentials, configuration, first boot, and troubleshooting. Release ZIPs are prebuilt; server owners do not need Node.js, npm, TypeScript, or this source tree. The dedicated server may run on Windows x64 or Linux x86-64; Hogwarts Legacy clients remain Windows.

Resources

Resource	Purpose
hmp-admin	Capability-gated moderation, corrective actions, recovery tools and persistent audit history.
hmp-mysql	Pooled, promise-based MySQL and MariaDB access.
hmp-lib	Shared utilities, input/control ownership, shortcut arbitration, validation, commands, targeting, localization and logging.
hmp-pvp	Composable, fail-closed PvP arbitration plus server-wide consent/lethal modes.
hmp-audio	Owner-scoped Wwise playback, aliases, audience helpers and reference-counted soundbanks.
hmp-ui	Shared notifications, dialogs, context menus, input and progress primitives.
hmp-core	Persistent accounts, identity links, characters, groups and metadata.
hmp-houses	Character houses, native robe/crest synchronization, group projection and an audited House Cup ledger.
hmp-characters	Multicharacter creation, selection and appearance flow.
hmp-spawn	Spawn selection and character-scoped last-location persistence.
hmp-inventory	Custom item slots, atomic container transfers and a unified, character-scoped view of native game items.
hmp-blips	Owner-scoped map, minimap, compass, search-area and group-aware player markers.
hmp-interact	Server-authoritative world zones, prompts, requirements and interaction handlers.
hmp-doors	Group-aware physical door and logical lock access with character-scoped grants.
hmp-world	Server-wide weather, time, season, mount-boundary, ambient-population and native-encounter defaults.
hmp-emotes	Curated synchronized emotes, account favorites, live alias editing and replaceable picker UI.
hmp-spells	Character-scoped spell grants, group-aware policy rules, bonus loadouts and advisory cast events.
hmp-activities	Public group discovery, role/team composition, readiness and reusable activity-session lifecycle.
hmp-duels	Consensual, non-lethal wizard duels using activity invitations and native PvP presentation.
hmp-shops	Server-owned catalogs, native Galleons, persistent stock and audited buy/sell flows.
hmp-progression	Character XP, native-confirmed levels, talent points, managed talents and replay-safe rewards.
hmp-banking	Character and organization accounts, native-cash exchange, atomic transfers and an audited ledger.
hmp-jobs	Persistent employment, grades, duty, permissions, management and bank-backed payroll.

Development

Node.js 22 or newer is required for Foundations's build tools. The generated resources target Node.js 22 and run on the newer embedded Node runtime shipped by HogwartsMP.

npm ci
npm test
npm run verify

Resource implementations are strict TypeScript under each resource's server/, client/, and shared/ directories. Builds remain bundled CommonJS JavaScript for server entrypoints (and IIFE JavaScript for browser clients) under dist/; runtime manifests continue to reference those generated JavaScript files. Source-level unit tests use tsx, while smoke tests execute the compiled bundles.

npm run package writes a ready-to-load pack under build/hmp-foundations/resources/. Runtime artifacts contain bundled dependencies: server owners do not run npm inside the game-server image.

For deployment, use the installation and start-order guide and database guide. A copy-ready configuration set ships in examples/config, and supported runtime combinations are recorded in the compatibility matrix. For structured playtest coverage and issue reports, use the closed testing guide.

The repository also publishes ghcr.io/<owner>/<repository>:edge from main and versioned tags from releases. This resource-pack image is build input for the runnable Foundations server variant; server owners normally use that server image or the downloadable ZIP instead of pulling it directly.

Versioning

Foundations uses one lockstep version for the pack and every first-party resource it contains. Install, upgrade, and roll back the twenty-three resources as one unit. Before 1.0.0, minor releases may contain breaking API, configuration, or schema changes; patch releases are intended to remain compatible within their minor line. See the full version policy and changelog.

License

HMP Foundations uses the same MafiaHub OSS license as the main HogwartsMP mod repository.