### Copy example configuration to server data directory Source: https://github.com/hogwarts-mp/foundations/blob/main/INSTALL.md Run from the directory containing the extracted hmp-foundations folder on Linux. Copies the release's examples/config/data contents into /opt/hogwartsmp/data/. ```sh sudo cp -a hmp-foundations/examples/config/data/. /opt/hogwartsmp/data/ ``` -------------------------------- ### Create environment file and enable systemd service Source: https://github.com/hogwarts-mp/foundations/blob/main/INSTALL.md Commands to create the root-owned, group-readable environment file /etc/hogwartsmp/foundations.env, reload systemd, enable and start the hogwartsmp service, and follow its logs. Assumes a hogwartsmp system user and group already exist. ```sh sudo install -d -o root -g hogwartsmp -m 0750 /etc/hogwartsmp sudo install -o root -g hogwartsmp -m 0640 /dev/null /etc/hogwartsmp/foundations.env sudoedit /etc/hogwartsmp/foundations.env sudo systemctl daemon-reload sudo systemctl enable --now hogwartsmp.service sudo journalctl -u hogwartsmp.service -f ``` -------------------------------- ### Healthy startup log output Source: https://github.com/hogwarts-mp/foundations/blob/main/INSTALL.md Example of healthy first-boot logs: MySQL connection followed by ready messages from database-backed resources. Do not admit players if any Foundations resource logs 'Startup failed'. ```text [hmp-mysql] connected to 127.0.0.1:3306/hogwartsmp [hmp-core] Accounts, characters, groups and metadata are ready [hmp-progression] Character progression, replay-safe rewards, and managed talents ready ``` -------------------------------- ### start(starter, mode?, solo?) Source: https://github.com/hogwarts-mp/foundations/blob/main/gamemodes/resources/hmp-quidditch/README.md Starts a Quidditch match with the specified starter, mode, and solo flag. ```APIDOC ## [FUNCTION] start(starter, mode?, solo?) ### Description Starts a Quidditch match with the specified starter, mode, and solo flag. ### Method FUNCTION ### Endpoint start(starter, mode?, solo?) ### Parameters #### Parameters - **starter** (string) - Required - The player who starts the match. - **mode** (string) - Optional - The match mode. - **solo** (boolean) - Optional - Indicates a solo match. ### Response #### Success Response - **result** (object) - The result of the start operation. ``` -------------------------------- ### Start Foundations resources in dependency order Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-inventory/README.md List of resources to start in order, with hmp-inventory last. ```text hmp-mysql hmp-lib hmp-core hmp-characters hmp-spawn hmp-inventory ``` -------------------------------- ### Install, test, and verify Foundations build tools Source: https://github.com/hogwarts-mp/foundations/blob/main/README.md Run these commands in the repository root to install dependencies, run tests, and verify the build. Requires Node.js 22 or newer. The generated resources target Node.js 22 and run on the newer embedded Node runtime shipped by HogwartsMP. ```sh npm ci npm test npm run verify ``` -------------------------------- ### Build from source with npm Source: https://github.com/hogwarts-mp/foundations/blob/main/INSTALL.md Install dependencies and run verification before building the pack. Requires Node.js 22 or newer and npm. Output is written to build/hmp-foundations. ```sh npm ci npm run verify ``` -------------------------------- ### hmp-business.json configuration example Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-business/README.md Example configuration file. Copy examples/config/data/hmp-business.json to /data/hmp-business.json or point HMP_BUSINESS_CONFIG at a file. The example declares Pippin's with its Hogsmeade counter; it only comes alive once a gameplay resource registers the pippins job. Remove the data-declared pippins entry from data/hmp-shops.json when switching to the player-run version, or both vendors stand on the same spot. ```json { "prices": { "floor": 1, "ceiling": 1000000, "ceilings": { "galleons": 100000 }, "buybacks": { "enabled": false, "maxRatio": 0.5, "referenceValues": { "native:wiggenweld_potion": 20 } } }, "houseCut": { "percent": 0, "organizationId": "treasury", "label": "Treasury", "currency": "galleons" }, "commands": { "enabled": true, "command": "business", "adminGroups": [{ "key": "admin", "minimumGrade": 1 }] }, "businesses": [] } ``` -------------------------------- ### Windows launch with HMP_ADMIN_BOOTSTRAP_SECRET Source: https://github.com/hogwarts-mp/foundations/blob/main/INSTALL.md Launch the server from PowerShell with the working directory set to . Set HMP_ADMIN_BOOTSTRAP_SECRET to a long random value before starting HogwartsMPServer.exe. Relative paths like data/hmp-mysql.json resolve from the working directory. ```powershell Set-Location C:\HogwartsMPServer $env:HMP_ADMIN_BOOTSTRAP_SECRET = "REPLACE_WITH_A_LONG_RANDOM_SECRET" .\HogwartsMPServer.exe ``` -------------------------------- ### Business setup commands Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-business/README.md Administrator commands to create the business, place a counter, set the vendor, set the duty point, add an offer, and seed stock. These commands are run sequentially to set up the business. ```text /business create pippins pippins J. Pippin's Potions /business shop pippins hogsmeade Hogsmeade counter /business vendor pippins hogsmeade PercivalPippin 30 /business dutypoint pippins hogsmeade /business offer pippins hogsmeade native:wiggenweld_potion 25 0.4 6 wiggenweld /business stock pippins hogsmeade wiggenweld 12 ``` -------------------------------- ### /quidditch start [solo] Source: https://github.com/hogwarts-mp/foundations/blob/main/gamemodes/resources/hmp-quidditch/README.md Starts a Quidditch match with the specified mode and optional solo flag. ```APIDOC ## [COMMAND] /quidditch start [solo] ### Description Starts a Quidditch match with the specified mode and optional solo flag. ### Method COMMAND ### Endpoint /quidditch start [solo] ### Parameters #### Path Parameters - **mode** (string) - Required - The match mode (e.g., standard, overtime). - **solo** (boolean) - Optional - Indicates a solo match. ### Response #### Success Response - **message** (string) - Confirmation that the match has started. ``` -------------------------------- ### Build and Verification Commands Source: https://github.com/hogwarts-mp/foundations/blob/main/gamemodes/resources/hmp-quidditch/README.md Commands to install dependencies, build, test, and run smoke tests for the hmp-quidditch workspace from the Foundations repository root. Requires a HogwartsMP build with physics, simulated, attachTo, and setVelocity support. ```text npm install npm run build -w hmp-quidditch npm test -w hmp-quidditch npm run smoke -w hmp-quidditch ``` -------------------------------- ### Create hmp-mysql.json configuration file Source: https://github.com/hogwarts-mp/foundations/blob/main/DATABASE.md Creates a JSON configuration file at /data/hmp-mysql.json. Restrict access because it contains a database password. ```json { "enabled": true, "host": "127.0.0.1", "port": 3306, "user": "hogwartsmp", "password": "REPLACE_GAME_PASSWORD", "database": "hogwartsmp", "connectionLimit": 10, "queueLimit": 0, "connectTimeout": 10000, "ssl": false, "charset": "utf8mb4", "timezone": "Z", "dateStrings": true } ``` -------------------------------- ### Launch HogwartsMP server with PowerShell environment variables Source: https://github.com/hogwarts-mp/foundations/blob/main/DATABASE.md Sets HMP_MYSQL_URL for a one-session PowerShell launch. Closing the PowerShell window discards the variables. ```powershell Set-Location C:\HogwartsMPServer $env:HMP_MYSQL_URL = "mysql://hogwartsmp:REPLACE_GAME_PASSWORD@127.0.0.1:3306/hogwartsmp" .\HogwartsMPServer.exe ``` -------------------------------- ### Launch HogwartsMP server with Linux shell environment variables Source: https://github.com/hogwarts-mp/foundations/blob/main/DATABASE.md Sets HMP_MYSQL_URL for a one-session Linux shell launch. Closing the shell discards the variable. ```sh cd /opt/hogwartsmp export HMP_MYSQL_URL='mysql://hogwartsmp:REPLACE_GAME_PASSWORD@127.0.0.1:3306/hogwartsmp' ./HogwartsMPServer ``` -------------------------------- ### Expected server directory layout after installing hmp-foundations Source: https://github.com/hogwarts-mp/foundations/blob/main/INSTALL.md Shows the required layout under after copying the release's resources directory. There must be exactly thirty top-level hmp-* directories, with no extra nesting level such as resources/hmp-foundations/resources/hmp-core. On Linux, resource and configuration names are case-sensitive. ```text / ├── HogwartsMPServer.exe # Windows │ or HogwartsMPServer # Linux ├── data/ └── resources/ ├── hmp-mysql/ │ ├── package.json │ └── dist/ ├── hmp-core/ │ ├── package.json │ └── dist/ ├── ... └── hmp-webhooks/ ├── package.json └── dist/ ``` -------------------------------- ### Extract and copy hmp-foundations resources on Linux Source: https://github.com/hogwarts-mp/foundations/blob/main/INSTALL.md Commands to create the server directories, copy all hmp-* resources from the release, and make the server executable. Replace /opt/hogwartsmp with the actual server root. Run the server as a dedicated, unprivileged service account and make that account the owner of the writable data and logs directories; do not solve permission errors with chmod -R 777. ```sh sudo mkdir -p /opt/hogwartsmp/resources /opt/hogwartsmp/data sudo cp -a hmp-foundations/resources/hmp-* /opt/hogwartsmp/resources/ sudo chmod +x /opt/hogwartsmp/HogwartsMPServer ``` -------------------------------- ### hmp-inventory resource manifest (mafiahub) Source: https://github.com/hogwarts-mp/foundations/blob/main/README.md Example resource manifest for hmp-inventory. Declares ordered mafiahub.serverScripts and mafiahub.clientScripts lists, plus mafiahub.files for the generated bundle and any pages, fonts, icons, or data. Paths must be relative to the resource root and point at built files under dist/. Avoid dist/** or dist/*.js because server bundles share that directory. ```json "mafiahub": { "serverScripts": ["dist/server.js"], "clientScripts": ["dist/client.js"], "files": ["dist/client.js", "dist/index.html", "dist/fonts/**", "dist/icons/**"] } ``` -------------------------------- ### Set individual HMP_MYSQL_* environment variables Source: https://github.com/hogwarts-mp/foundations/blob/main/DATABASE.md Sets individual connection variables to avoid URL encoding issues. These values must be added to the service, process manager, container configuration, or shell that starts the server. ```text HMP_MYSQL_HOST=127.0.0.1 HMP_MYSQL_PORT=3306 HMP_MYSQL_USER=hogwartsmp HMP_MYSQL_PASSWORD=REPLACE_GAME_PASSWORD HMP_MYSQL_DATABASE=hogwartsmp ``` -------------------------------- ### Logical backup with mysqldump Source: https://github.com/hogwarts-mp/foundations/blob/main/DATABASE.md Basic logical backup command for the hogwartsmp database before a Foundations upgrade. Uses --single-transaction for a consistent snapshot and writes to hogwartsmp-backup.sql. ```sh mysqldump --host=127.0.0.1 --port=3306 --user=hogwartsmp --password --single-transaction --result-file=hogwartsmp-backup.sql hogwartsmp ``` -------------------------------- ### Create database and user for HogwartsMP Source: https://github.com/hogwarts-mp/foundations/blob/main/DATABASE.md Run these SQL statements as a database administrator to create an empty database and a database-scoped user. Replace the password before running. Use 'localhost' when the game server and database are on the same machine; otherwise, replace it with the game server's exact IP address or a restricted subnet. Do not use '%' unless the network and firewall already provide equivalent restriction. If the database runs with skip_name_resolve, create and grant 'hogwartsmp'@'127.0.0.1' instead. ```sql CREATE DATABASE `hogwartsmp` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER 'hogwartsmp'@'localhost' IDENTIFIED BY 'REPLACE_WITH_A_LONG_RANDOM_PASSWORD'; GRANT ALL PRIVILEGES ON `hogwartsmp`.* TO 'hogwartsmp'@'localhost'; ``` -------------------------------- ### systemd unit for HogwartsMP server Source: https://github.com/hogwarts-mp/foundations/blob/main/INSTALL.md Minimal systemd unit for a persistent HogwartsMP server. Uses WorkingDirectory=/opt/hogwartsmp, loads environment from /etc/hogwartsmp/foundations.env, and restarts on failure. Save as /etc/systemd/system/hogwartsmp.service. Do not place sudo in ExecStart and do not run the server as root. ```ini [Unit] Description=HogwartsMP dedicated server Wants=network-online.target After=network-online.target [Service] Type=simple User=hogwartsmp Group=hogwartsmp WorkingDirectory=/opt/hogwartsmp EnvironmentFile=/etc/hogwartsmp/foundations.env ExecStart=/opt/hogwartsmp/HogwartsMPServer Restart=on-failure RestartSec=5 [Install] WantedBy=multi-user.target ``` -------------------------------- ### Check tables and migration versions Source: https://github.com/hogwarts-mp/foundations/blob/main/DATABASE.md SQL queries for a database administrator to list all tables in the hogwartsmp database and view applied migration versions and checksums from hmp_schema_migrations. ```sql SHOW TABLES FROM `hogwartsmp`; SELECT resource, version, name, applied_at FROM `hogwartsmp`.`hmp_schema_migrations` ORDER BY resource, version; ``` -------------------------------- ### Create, discover, join, ready, and start a session Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-activities/README.md Shows the full lifecycle for a group: create a session, discover sessions needing a role, join, set ready, and start. The discover call returns matching sessions, and start requires an actor. ```TypeScript const group = await Activities.sessions.create(player, "dungeon:ruins", { title: "First clear — new players welcome", role: "caster", metadata: { difficulty: "normal" }, }); const needsHealer = Activities.sessions.discover(player, { activityId: "dungeon:ruins", role: "healer", }); await Activities.sessions.join(healer, needsHealer[0].id, { role: "healer" }); await Activities.sessions.setReady(healer, group.id, true); await Activities.sessions.start(group.id, { actor: groupLeader }); ``` -------------------------------- ### Verify database account with mysql client Source: https://github.com/hogwarts-mp/foundations/blob/main/DATABASE.md Run this command from the same machine that will run HogwartsMP to verify the account. Replace '127.0.0.1' with the database hostname for a remote database. Also configure the database listener, firewall, and TLS according to the database provider's instructions. Never expose port 3306 directly to the public internet. ```sh mysql --host=127.0.0.1 --port=3306 --user=hogwartsmp --password --database=hogwartsmp --execute="SELECT 1" ``` -------------------------------- ### Database connection success log Source: https://github.com/hogwarts-mp/foundations/blob/main/DATABASE.md Expected log output when the HogwartsMP server successfully connects to the database. The placeholders HOST, PORT, and DATABASE are replaced with actual values. ```text [hmp-mysql] connected to HOST:PORT/DATABASE ``` -------------------------------- ### Run MySQL 8.4 Docker container with persistent storage Source: https://github.com/hogwarts-mp/foundations/blob/main/DATABASE.md Creates a MySQL 8.4 container named hogwartsmp-mysql with persistent storage, publishing only on local loopback. Replace REPLACE_ROOT_PASSWORD and REPLACE_GAME_PASSWORD. Wait for the server to be ready before configuring Foundations. ```sh docker run --name hogwartsmp-mysql --restart unless-stopped -e MYSQL_ROOT_PASSWORD=REPLACE_ROOT_PASSWORD -e MYSQL_DATABASE=hogwartsmp -e MYSQL_USER=hogwartsmp -e MYSQL_PASSWORD=REPLACE_GAME_PASSWORD -p 127.0.0.1:3306:3306 -v hogwartsmp-mysql-data:/var/lib/mysql -d mysql:8.4 ``` -------------------------------- ### Set HMP_MYSQL_URL environment variable Source: https://github.com/hogwarts-mp/foundations/blob/main/DATABASE.md Sets a connection URL for the HogwartsMP dedicated server. Characters such as @, :, /, #, and % in the password must be percent-encoded. ```text HMP_MYSQL_URL=mysql://hogwartsmp:REPLACE_GAME_PASSWORD@127.0.0.1:3306/hogwartsmp ``` -------------------------------- ### hmp-doors JSON configuration example Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-doors/README.md Example configuration for hmp-doors. Lower priority numbers are stronger; at equal priority, lock beats deny, which beats allow, and a personal grant beats all three. Rules can target physical doors, gates, logical locks, or the Alohomora master policy. match.groups uses effective hmp-core groups; groupMode defaults to any. ```json { "command": "doors", "enableCommands": true, "adminGroups": [{ "key": "admin", "minimumGrade": 1 }], "shareUnlocks": false, "gateSchedule": "local", "heldGates": {}, "rules": [ { "priority": 1000, "action": "allow", "doors": "*" }, { "priority": 500, "action": "deny", "doors": ["BP_Door_Headmaster"] }, { "priority": 100, "action": "allow", "doors": ["BP_Door_Headmaster"], "match": { "groups": [{ "key": "staff", "minimumGrade": 1 }], "groupMode": "any" } } ] } ``` -------------------------------- ### Environment variables for admin bootstrap and webhooks Source: https://github.com/hogwarts-mp/foundations/blob/main/INSTALL.md Set these in the process that launches the server; Foundations does not read environment.example or .env files. The admin bootstrap secret must be at least 16 bytes and grants session-only access through the masked /admin prompt. Do not put it in chat, commit it, or use it as a permanent staff identity system. ```text HMP_ADMIN_BOOTSTRAP_SECRET=REPLACE_WITH_A_LONG_RANDOM_SECRET HMP_ADMIN_REQUIRE_VERIFIED=true HMP_ADMIN_UNSAFE_ASSERTED_BANS=false # Optional; also set enabled=true in data/hmp-webhooks.json or HMP_WEBHOOKS_ENABLED=true. HMP_WEBHOOKS_DISCORD_URL=https://discord.com/api/webhooks/... ``` -------------------------------- ### Linux direct shell launch with HMP_ADMIN_BOOTSTRAP_SECRET Source: https://github.com/hogwarts-mp/foundations/blob/main/INSTALL.md Launch the server directly from a shell with the working directory set to /opt/hogwartsmp. The export of HMP_ADMIN_BOOTSTRAP_SECRET lasts only for that shell; use a service manager for persistent operation. ```sh cd /opt/hogwartsmp export HMP_ADMIN_BOOTSTRAP_SECRET='REPLACE_WITH_A_LONG_RANDOM_SECRET' ./HogwartsMPServer ``` -------------------------------- ### hmp-loot server API usage Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-loot/README.md TypeScript example showing how to access the hmp-loot server API via Imports.get("hmp-loot"). Demonstrates listing, getting, recording, resetting lootables, and subscribing to take events. ```typescript const loot = Imports.get("hmp-loot"); loot.lootables.list(); // definitions with their Lootables id and shared take loot.lootables.get("courtyard-chest"); loot.lootables.record("courtyard-eggs", 42); // a character's live take, or null loot.lootables.reset("courtyard-eggs", 42); // or reset(key) for every take loot.lootables.onTaken((take) => { // { key, characterId, accountId, takenAt, respawnAt, player, items } }); loot.status(); ``` -------------------------------- ### Define startingItems with bare names or objects Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-inventory/README.md startingItems is granted once per character on first load after creation. Existing characters are not affected. Entries can be bare item names or objects with name, amount, and optional metadata. ```json { "startingItems": [ "housebroom", { "name": "sealed_letter", "amount": 3 }, { "name": "native:wiggenweld_potion", "amount": 5 }, { "name": "evidence_bag", "amount": 1, "metadata": { "issued": true } } ] } ``` -------------------------------- ### express.train.depart() Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-express/README.md Starts the train on its route. Returns false if the host refuses. ```APIDOC ## train.depart() ### Description Starts the train on its route. Returns false if the host refuses. ### Method POST ### Endpoint express.train.depart() ### Response #### Success Response - **boolean** - true if departure started, false if refused ``` -------------------------------- ### get Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-npcs/README.md Retrieves an NPC by its ID. Returns the NPC object if it exists. ```APIDOC ## get ### Description Retrieves an NPC by its ID. Returns the NPC object if it exists. ### Method get ### Parameters #### Path Parameters - **id** (string) - Required - The ID of the NPC to retrieve. ### Request Example ```ts npcs.get(enemy.id); ``` ### Response Returns the NPC object. ``` -------------------------------- ### Business.ui.manage Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-business/README.md Opens the management menu for businesses the player manages. Can optionally open a specific shop directly. ```APIDOC ## Business.ui.manage ### Description Opens the management menu for businesses the player manages. Can optionally open a specific shop directly. ### Method Business.ui.manage(player, shopId?) ### Parameters - **player** (string) - Required - Player identifier. - **shopId** (string) - Optional - Identifier of the shop to open directly. ### Request Example ```ts Business.ui.manage(player); Business.ui.manage(player, "pippins"); ``` ### Response No return value. ``` -------------------------------- ### Declare resource dependency for hmp-mysql Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-mysql/README.md Declares hmp-mysql as a resource dependency so it starts first. The version is specified as 0.10.0. ```json "resourceDependencies": [{ "name": "hmp-mysql", "version": "0.10.0" }] ``` -------------------------------- ### MySQL.ready() Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-mysql/README.md Returns `false` when the database is disabled or unreachable, making it suitable for health checks. ```APIDOC ## MySQL.ready() ### Description Returns `false` when the database is disabled or unreachable, making it suitable for health checks. ### Method ready ### Response #### Success Response Returns a boolean indicating readiness. ``` -------------------------------- ### policy.syncAll() Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-doors/README.md Recomputes and pushes complete client policies for all players. Skips players without an hmp-core session yet; hmp:session:ready syncs them moments later. ```APIDOC ## policy.syncAll() ### Description Recomputes and pushes complete client policies for all players. ### Method Function call ### Parameters None ### Returns - Nothing (skips players without an hmp-core session yet). ``` -------------------------------- ### progression.get(target) Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-progression/README.md Gets or initializes a character profile for the given target. This is used to retrieve the current progression state of a character. ```APIDOC ## progression.get(target) ### Description Gets or initializes a character profile for the given target. ### Method Function call ### Parameters - **target** (character) - Required - The character whose profile to get or initialize. ### Returns - Character profile object. ``` -------------------------------- ### movement.get Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-npcs/README.md Gets the current movement state of an NPC. Returns null if the NPC is not managed or on a host without movement support. ```APIDOC ## movement.get ### Description Gets the current movement state of an NPC. Returns null if the NPC is not managed or on a host without movement support. ### Method movement.get ### Parameters #### Path Parameters - **id** (string) - Required - The ID of the NPC. ### Request Example ```ts npcs.movement.get(guard.id); ``` ### Response Returns an object with `state`, `waypoints`, `idle`, and `home`. ``` -------------------------------- ### Import hmp-mysql and run queries Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-mysql/README.md Imports the hmp-mysql module and demonstrates query, single, and scalar methods. Supports positional ? and named :name placeholders. query uses safe driver escaping and supports conveniences like array expansion. ```javascript /** @type {import("../../hmp-mysql/types").HmpMySQL} */ const MySQL = Imports.get("hmp-mysql"); const characters = await MySQL.query( "SELECT * FROM characters WHERE account_id = ?", [accountId], ); const character = await MySQL.single( "SELECT * FROM characters WHERE id = :id", { id: characterId }, ); const name = await MySQL.scalar( "SELECT name FROM characters WHERE id = ?", [characterId], ); ``` -------------------------------- ### Business.offers.setPrices Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-business/README.md Sets the buy price and buyback ratio for an offer in a shop. Requires the actor to have shop.manage permission unless admin is true. ```APIDOC ## Business.offers.setPrices ### Description Sets the buy price and buyback ratio for an offer in a shop. Requires the actor to have shop.manage permission unless admin is true. ### Method await Business.offers.setPrices(shopId, counterId, itemId, { buyPrice, buybackRatio }, { actor, reason }) ### Parameters - **shopId** (string) - Required - Identifier of the shop. - **counterId** (string) - Required - Identifier of the counter. - **itemId** (string) - Required - Identifier of the item. - **buyPrice** (number) - Required - The price customers pay. - **buybackRatio** (number) - Required - The buyback share (0-1) when buybacks are enabled. - **actor** (string) - Optional - Player or character id performing the action. - **reason** (string) - Optional - Reason for the price change. ### Request Example ```ts await Business.offers.setPrices("pippins", "hogsmeade", "wiggenweld", { buyPrice: 30, buybackRatio: 0.4 }, { actor: player, reason: "Winter prices" }); ``` ### Response No return value. ``` -------------------------------- ### hmp-emotes configuration with aliases Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-emotes/README.md Configuration file example for hmp-emotes. Aliases can be a path or an object with path, kind, and channel. Copy to the server's data directory. ```json { "aliases": { "wave": { "path": "/Game/Pawn/Student/Abilities/PartialBody/Waving/ABL_Waving.ABL_Waving_C", "kind": "ability", "channel": "PartialBody" } } } ``` -------------------------------- ### Configure hmp-inventory with data/hmp-inventory.json Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-inventory/README.md Optional configuration file for hmp-inventory. Configure hmp-mysql first. ```json { "slots": 36, "maxWeight": 60, "autoSaveMs": 30000, "allowInventoryCommand": true, "ui": { "url": "fw://resources/hmp-inventory/dist/index.html" }, "items": [], "startingItems": [] } ``` -------------------------------- ### Secure hmp-mysql.json with chown and chmod Source: https://github.com/hogwarts-mp/foundations/blob/main/DATABASE.md Makes the JSON configuration file readable only by the service account on Linux. Replace hogwartsmp:hogwartsmp when the service uses a different account. ```sh sudo chown hogwartsmp:hogwartsmp /opt/hogwartsmp/data/hmp-mysql.json sudo chmod 600 /opt/hogwartsmp/data/hmp-mysql.json ``` -------------------------------- ### Business.books.summary Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-business/README.md Returns a summary of the shop's books, including organization balance, today's sales per counter, and stock levels. Requires the actor to have shop.manage permission unless admin is true. ```APIDOC ## Business.books.summary ### Description Returns a summary of the shop's books, including organization balance, today's sales per counter, and stock levels. Requires the actor to have shop.manage permission unless admin is true. ### Method await Business.books.summary(shopId, { actor }) ### Parameters - **shopId** (string) - Required - Identifier of the shop. - **actor** (string) - Optional - Player or character id performing the action. ### Request Example ```ts const books = await Business.books.summary("pippins", { actor: player }); ``` ### Response Returns a summary object with organization balance, sales per counter, and stock levels. ``` -------------------------------- ### Read a player's waypoint with Blips.waypoints.get and event Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-blips/README.md Each client reports its own map waypoint to the server as it is placed, moved, or lifted. get returns { x, y, z, target, areaId } or null. Coordinates are world centimetres; target is the beacon name when dropped on a map icon (e.g. "FT_HW_GreatHall") or null on open ground where z is near terrain. The hmp:blips:waypoint event fires with waypoint null once lifted. Requires HogwartsMP 1.10 or newer; on older hosts get() returns null. ```TypeScript Blips.waypoints.get(player); // { x, y, z, target, areaId } | null Events.on("hmp:blips:waypoint", ({ player, waypoint, previous }) => { // waypoint is null once it is lifted }); ``` -------------------------------- ### policy.sync(player) Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-doors/README.md Recomputes and pushes the complete client policy for a single player. Returns null. ```APIDOC ## policy.sync(player) ### Description Recomputes and pushes the complete client policy for a single player. ### Method Function call ### Parameters - **player** - Required - The player to sync the policy for. ### Returns - null ``` -------------------------------- ### Hmp.rateLimit.create Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-lib/README.md Creates a rate limiter with a limit and window. Use the `allow` method to check if a player is allowed, and `sweep` to clean up expired keys. ```APIDOC ## Hmp.rateLimit.create ### Description Creates a rate limiter with a limit and window. Use the `allow` method to check if a player is allowed, and `sweep` to clean up expired keys. ### Method create ### Parameters - **limit** (number) - Required - Maximum number of allowed actions within the window. - **windowMs** (number) - Required - The time window in milliseconds. ### Returns - **limiter** (object) - The limiter object with `allow` and `sweep` methods. ### Example ```js const casts = Hmp.rateLimit.create({ limit: 6, windowMs: 1000 }); Events.onClient("spellCast", (player, payload) => { if (!casts.allow(player.id)) return; // Validate and process the advisory payload. }); ``` ### allow Method - **playerId** (string) - Required - The player's ID. - **Returns** (object) - `{ allowed, used, remaining, dropped, resetAt }`. ### sweep Method - **No parameters** - Call from an existing maintenance tick when keys are unbounded. ``` -------------------------------- ### Query points standings, get, history, and pending Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-houses/README.md Retrieves current standings, a house's points, point history, and pending transactions. Useful for monitoring and recovery. ```ts await Houses.points.standings(); await Houses.points.get("ravenclaw"); await Houses.points.history("ravenclaw", 50); await Houses.points.pending(50); ``` -------------------------------- ### policy.resolve/sync/syncAll Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-spells/README.md Inspect or push complete policies. `sync` returns `null` and `syncAll` skips a player with no `hmp-core` session yet; `hmp:session:ready` syncs them moments later. ```APIDOC ## policy.resolve/sync/syncAll ### Description Inspect or push complete policies. `sync` returns `null` and `syncAll` skips a player with no `hmp-core` session yet; `hmp:session:ready` syncs them moments later. ### Method Not specified ### Endpoint Not specified ### Parameters Not specified ### Request Example Not specified ### Response Not specified ``` -------------------------------- ### worldstate.systems.register(name, config) Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-worldstate/README.md Registers a new system with validation and entry cap. ```APIDOC ## [METHOD] worldstate.systems.register(name, config) ### Description Registers a new system with validation and entry cap. ### Method METHOD ### Endpoint worldstate.systems.register(name, config) ### Parameters #### Path Parameters - **name** (string) - Required - The name of the system - **config** (object) - Required - Configuration object with validateValue, maxEntries, and broadcast ### Response #### Success Response - **success** (boolean) - Whether the registration succeeded ``` -------------------------------- ### Membership set, get, and clear Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-houses/README.md Sets, retrieves, and clears a character's house membership. Requires a resource, actor, and reason. Clearing removes all Foundations-owned house:* projections. ```ts const Houses = Imports.get("hmp-houses"); await Houses.membership.set(player, "gryffindor", { resource: "hmp-sorting", actor: player, reason: "Sorting ceremony", }); const membership = await Houses.membership.get(player); await Houses.membership.clear(player, { resource: "hmp-admin", actor: administrator, reason: "Correcting an invalid assignment", }); ``` -------------------------------- ### MySQL.migrate(resource, migrations) Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-mysql/README.md Runs a resource-owned migration list. It serializes concurrent starts with a MySQL advisory lock, records checksums in hmp_schema_migrations, skips applied versions, and refuses to continue if an applied migration was edited later. ```APIDOC ## MySQL.migrate(resource, migrations) ### Description Runs a resource-owned migration list. It serializes concurrent starts with a MySQL advisory lock, records checksums in hmp_schema_migrations, skips applied versions, and refuses to continue if an applied migration was edited later. ### Method migrate ### Parameters - **resource** (string) - Required - The resource name that owns the migration list. - **migrations** (array) - Required - An array of migration objects, each with `version`, `name`, and either `up` (SQL string) or `statements` (array of SQL strings). ### Request Example ```js await MySQL.migrate("my-resource", [ { version: 1, name: "create characters", up: `CREATE TABLE IF NOT EXISTS characters ( id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, name VARCHAR(80) NOT NULL ) ENGINE=InnoDB`, }, { version: 2, name: "index character names", statements: [ "CREATE INDEX idx_characters_name ON characters (name)", ], }, ]); ``` ### Response #### Success Response Resolves when all migrations are applied successfully. #### Error Response Rejects with the original error; transactions roll back and rethrow the error. ``` -------------------------------- ### Gauntlet Commands Source: https://github.com/hogwarts-mp/foundations/blob/main/gamemodes/resources/hmp-gauntlet/README.md Lists all slash commands for the hmp-gauntlet gamemode. `start` creates a lobby with the default preset without opening the configuration screen; `top` is public, while the remaining commands operate on the current activity. ```text /gauntlet menu /gauntlet start /gauntlet join /gauntlet begin /gauntlet stop /gauntlet status /gauntlet top [preset] ``` -------------------------------- ### environment.setTime(hour, minute, second) Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-world/README.md Sets the time of day in the world environment. The time is specified in hours, minutes, and seconds. ```APIDOC ## environment.setTime(hour, minute, second) ### Description Sets the time of day in the world environment. ### Parameters - **hour** (number) - Required - The hour (0-23). - **minute** (number) - Required - The minute (0-59). - **second** (number) - Required - The second (0-59). ### Response No return value. ``` -------------------------------- ### policy.sync(player) Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-world/README.md Synchronizes the policy with a specific player. ```APIDOC ## policy.sync(player) ### Description Synchronizes the policy with a specific player. ### Parameters - **player** (Player) - Required - The player to sync with. ### Response No return value. ``` -------------------------------- ### Register an activity definition with hmp-activities Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-activities/README.md Defines a dungeon activity type with roles, capacity, ready checks, and disconnect policy. The canJoin callback returns an error string or true, and onStarted is invoked when the session starts. ```TypeScript const Activities = Imports.get("hmp-activities"); Activities.definitions.register({ id: "dungeon:ruins", resource: "hmp-dungeon-lfg", label: "Ruins expedition", minimumPlayers: 3, maximumPlayers: 5, requireReady: true, disconnectPolicy: "remove", scope: "areaAndVirtualWorld", roles: [ { id: "healer", label: "Healer", min: 1, max: 1 }, { id: "caster", label: "Caster", min: 1, max: 2 }, { id: "fighter", label: "Fighter", min: 1, max: 2 }, ], async canJoin({ player, role }) { // Check level, spell kits, dungeon lockouts, or another gameplay-owned rule here. return role === "healer" && !await canHeal(player) ? "Equip an approved healing kit before taking the healer role." : true; }, onStarted({ session }) { beginDungeonInstance(session); }, }); ``` -------------------------------- ### Register a command router with Events Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-lib/README.md Creates a command router with a prefix and registers a 'robe' command with aliases, usage, and a guard. The guard returns an error message if the player is not connected. The handle function is registered with the resource's Events to maintain ownership and cleanup on reload. ```javascript const commands = Hmp.command.createRouter({ prefix: "[robes]" }); commands.register("robe", { aliases: ["outfit"], usage: "/robe ", guard: ({ player }) => player.connected || "You are not connected.", }, ({ player, args, resolvePlayer, reply, usage }) => { const result = resolvePlayer(args[0] || "me"); if (!result.ok) return reply(result.reason === "ambiguous" ? "That name is ambiguous." : usage); reply(`Selected ${Hmp.player.format(result.player)}.`); }); Events.on("chatCommand", commands.handle); ``` -------------------------------- ### Closed-testing activity commands Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-activities/README.md Commands to exercise the test-party activity definition during closed testing. Requires enableTestActivity in data/hmp-activities.json and a healer, caster, and at least two total players. Disable the example definition after closed testing. ```text /activities definitions /activities list /activities create foundations:test-party healer /activities join caster /activities ready [short-id] /activities start [short-id] /activities cancel [short-id] ``` -------------------------------- ### Resolve aliases and discover sound catalog Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-audio/README.md Raw event names always work. Aliases come from data/hmp-audio.json and are synchronized to clients. The catalog methods resolve, find the bank, get the stop event, and list aliases for a category. ```ts Audio.catalog.resolve("click"); // UI_Menu_Select Audio.catalog.bankFor("accio"); // Spells_Accio_AKB Audio.catalog.stopEventFor("accio"); // accio_release Audio.catalog.list("menu"); ``` -------------------------------- ### /worldstate resync Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-worldstate/README.md Re-sends the whole store to every player. ```APIDOC ## [COMMAND] /worldstate resync ### Description Re-sends the whole store to every player. ### Method COMMAND ### Endpoint /worldstate resync ### Parameters None ### Response #### Success Response - **success** (boolean) - Whether the resync was initiated ``` -------------------------------- ### Declare a spell lesson in lessons configuration Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-spells/README.md Declares a lesson in the `lessons` array, naming the spell it teaches and the lesson definition. The `lesson` starts from a stock `look` or brings its own `path`; the `id` cannot be a stock lesson's name. ```json { "lessons": [{ "id": "FirestormLesson", "spell": "Firestorm", "lesson": { "title": "Firestorm", "look": "Confringo", "chaser": 1.5 } }] } ``` -------------------------------- ### Spawn.ui.open Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-spawn/README.md Opens the spawn UI for a given player, allowing them to select a spawn location. ```APIDOC ## Spawn.ui.open ### Description Opens the spawn UI for a given player, allowing them to select a spawn location. ### Method open ### Parameters #### Request Body - **player** (object) - Required - The player object to open the UI for. ### Request Example ```js await Spawn.ui.open(player); ``` ### Response #### Success Response No return value. ``` -------------------------------- ### Send a message to a configured destination Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-webhooks/README.md Import the HmpWebhooks type, get the service via Imports.get, and call send with the destination name and a rich message. Returns whether the message entered the in-memory queue, not whether the remote endpoint accepted it. ```ts import type { HmpWebhooks } from "../../hmp-webhooks/types"; const Webhooks = Imports.get("hmp-webhooks"); const accepted = Webhooks.send("discord", { title: "Potion brewed", description: `${character.name} finished a Wiggenweld potion.`, color: 0x3ba55d, fields: [{ name: "Quality", value: "Excellent", inline: true }], timestamp: new Date().toISOString(), }); ``` -------------------------------- ### Shops.stock.set Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-shops/README.md Sets the initial persistent stock quantity for a specific offer. If the stock already exists, this does not overwrite the current quantity. ```APIDOC ## Shops.stock.set ### Description Sets the initial persistent stock quantity for a specific offer. If the stock already exists, this does not overwrite the current quantity. ### Method set ### Signature `Shops.stock.set(shopId, offerId, quantity)` ### Parameters - **shopId** (string) - Required - The identifier of the shop. - **offerId** (string) - Required - The identifier of the offer. - **quantity** (number) - Required - The initial stock quantity. ``` -------------------------------- ### Assign admin role via hmp-core groups.setAccount Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-admin/README.md Use a trusted server-side resource to assign a staff account its role once identities are live. This example sets the account to the 'admin' group with grade 2 and a source of 'staff-provisioning'. Requires the hmp-core import and is the recommended way to appoint the highest grade. ```ts const Core = Imports.get("hmp-core"); await Core.groups.setAccount(accountId, "admin", 2, { source: "staff-provisioning", }); ``` -------------------------------- ### Shops.stock.get Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-shops/README.md Retrieves the current stock quantity for a specific offer in a shop. Returns null if stock is unlimited. ```APIDOC ## Shops.stock.get ### Description Retrieves the current stock quantity for a specific offer in a shop. Returns null if stock is unlimited. ### Method get ### Signature `Shops.stock.get(shopId, offerId)` ### Parameters - **shopId** (string) - Required - The identifier of the shop. - **offerId** (string) - Required - The identifier of the offer. ### Returns - **stock** (number | null) - The current stock quantity, or null if unlimited. ``` -------------------------------- ### Set HMP_ADMIN_BOOTSTRAP_SECRET environment variable Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-admin/README.md Configure a temporary secret for the closed-test setup until the verified identity provider is ready. The secret must be at least 16 bytes, is read only from the environment, never stored in MySQL or configuration files, and must not be sent through chat. Access is discarded on disconnect or resource restart. ```text HMP_ADMIN_BOOTSTRAP_SECRET= ``` -------------------------------- ### setLoadoutSlot Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-spells/README.md Client resource exposes `setLoadoutSlot` against Foundations state. ```APIDOC ## setLoadoutSlot ### Description Client resource exposes `setLoadoutSlot` against Foundations state. ### Method Not specified ### Endpoint Not specified ### Parameters Not specified ### Request Example Not specified ### Response Not specified ``` -------------------------------- ### environment.state() Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-world/README.md Retrieves the current state of the world environment, including weather, time, season, and time scale. ```APIDOC ## environment.state() ### Description Returns the current environment state. ### Method state() ### Parameters None ### Response Returns the current environment state object. ``` -------------------------------- ### MySQL.status() Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-mysql/README.md Reports the sanitized target, state, and basic query counters. ```APIDOC ## MySQL.status() ### Description Reports the sanitized target, state, and basic query counters. ### Method status ### Response #### Success Response Returns an object containing the sanitized target, state, and basic query counters. ``` -------------------------------- ### policy.current() Source: https://github.com/hogwarts-mp/foundations/blob/main/resources/hmp-world/README.md Retrieves the current policy settings. ```APIDOC ## policy.current() ### Description Returns the current policy settings. ### Parameters None ### Response Returns the current policy object. ```