Notes:
- The server persists linkage data in apps//links.json as minimal overrides.
- On link, defaults are written to blueprint.json if not already present.

---

WebSocket protocol

URL: ws://localhost:8080/

$3

Asset URL convention: asset://. (e.g., asset://d2ab...c3.js). The server hashes local files and maps them for quick resolution.

---

Programmatic usage and custom service handlers

You can embed the server in your own tooling and implement the HTTP/WS behavior by providing a "service handler" object. The server wires routes to the methods of the service you pass to start(service).

$3

`js
// dev-server.js (in your project)
import { HyperfyAppServer } from '@drama.haus/app-server'

class MyServiceHandler {
// HTTP routes
async handleGetApps() { return { success: true, apps: [] } }
async handleGetLinkedApps(worldUrl) { return { success: true, apps: [] } }
async handleGetAppIsLinked(blueprintId, worldUrl) { return { success: true, isLinked: false } }
async handleGetApp(appName) { return { success: false, error: 'Not found', statusCode: 404 } }
async handleCreateApp(appName, body) { return { success: true, message: Created ${appName} } }
async handleUpdateAppScript(appName, body) { return { success: true, message: Updated ${appName} } }
async handleDeploy(appName, body) { return { success: true, message: Deployed ${appName} } }
async handleDeployLinked(appName, body) { return { success: true, message: Linked deploy ${appName} } }
async handleLink(appName, body) { return { success: true, message: Linked ${appName} } }
async handleUnlink(appName) { return { success: true, message: Unlinked ${appName} } }
async handleReset() { return { success: true, message: 'Reset complete' } }
}

async function main() {
const port = process.env.PORT || 8080
const server = new HyperfyAppServer(port, {
hotReload: true, // or use env/flags
fastifyOptions: { logger: false },
typescript: true // optional: prefer index.ts files; no transpile, typings only
})

// Optional: subscribe to WebSocket events
server.addConnectionHandler((ws, req) => {
console.log('client connected')
})
server.addMessageHandler('ping', (ws, msg) => {
// custom handling if desired (server auto-responds to ping already)
})

await server.start(new MyServiceHandler())
}

main()
`

Then add an npm script in your project:

`json
{
"scripts": {
"dev:hyperfy": "node dev-server.js"
}
}
`

$3

If you provide your own handler, implement the methods the HTTP routes call:
- handleGetApps()
- handleGetLinkedApps(worldUrl)
- handleGetAppIsLinked(blueprintId, worldUrl)
- handleGetApp(appName)
- handleCreateApp(appName, body)
- handleUpdateAppScript(appName, body)
- handleDeploy(appName, body)
- handleDeployLinked(appName, body)
- handleLink(appName, body)
- handleUnlink(appName)
- handleReset()

Additionally, you can listen to WebSocket events by subscribing on the HyperfyAppServer instance:
- connection, disconnect, websocket_error
- Per-message type event names (e.g., 'auth', 'blueprint_modified', 'asset_response', 'request_model_content', 'blueprint_response')

Use server.sendMessage(ws, payload) or server.broadcast(payload) to push messages to clients.

Note: The packaged default handler (HyperfyAppServerHandler) provides a robust filesystem-based implementation with hot reload, asset hashing, blueprint diffing, and linking. If you need that behavior, prefer running the binary directly via npx or reusing the package as a CLI in your scripts. When you implement a custom handler, you are responsible for these behaviors.

---

Development details

$3

1. Fork and clone the repo
2. Make changes
3. Run locally with npm run dev`
4. Submit a PR

Please keep code readable and avoid reformatting unrelated areas. Linting is minimal; prefer clear naming and small functions.

---

License

MIT