App server

[peezy]

App server

as per #110 (comment):

• devs can git clone a hyperfy "app server" or run something like npx hyperfy-app-server to generate a project
• inside that project they run npm run start to launch the app server
• now, inside ANY hyperfy world (localhost or even live domain) your browser will realise there is an app server running locally (automatically) and show a "local sync" button on the app (see img below)
• clicking this button will send the entire hyp to the app server, which then spawns a folder for the app with all the assets in it
• changing any of the files pushes it back to the world and it updates
  In the other direction, in the world when you click the + button to add an app, if you have an app server running it will also list those local apps there too, and when you add them to the world they will automatically be synced locally.

---

my proposal is to have a PUBLIC_DEV_SERVER flag that, when active, adds a new system to the client that attempts a connection with an app server on localhost:8080 (port can be changed). this system:

• checks if any apps are linked
• handles receiving updates for linked apps
• sends app updates to the app server
• sends requests for deployment of new apps
• sends assets to the app server

the app server itself is a small class that anyone can hook up handlers in order to create their own custom functionality for their use case (typescript? code splitting?). if we run node tools/server.js (which we should hook up to npx hyperfy app-server imo) it runs a basic server with hot reloading.

---

the idea of separating a thin server from the handlers enables people to build their own custom servers which could include code splitting, typescript, anything they need.

keeping the app server totally separate from the client but still requiring the auth token enables apps with custom deploy pipelines (with the node client) but still tied to a specific user (which might be handy if we ever add audit changes ("last change by: peezy")

---

what needs to be agreed upon for merging:

• do we keep this sample server on hyperfy codebase?
  • the benefit is that people devving on local worlds wouldnt need to set anything else up.
  • the con is that it might incentivize people to commit their apps code with the engine code. this might not be ideal
• if we go down this route, we should probably make a vibe coding starter kit repository with a server, some docs on scripting and instructions for claude code

[peezy]

@ashconnell @DevStarlight @saori-eth

would appreciate thoughts on the general idea and UX flow, is this on the right path?
detailed thoughts on what the API contract between a hyperfy client and an app server should look like would be also appreciated

[saori-eth]

Generally, I like the path.
If we're keeping it in the main repo I think we should embrace it and run it with the regular dev command, not gitignore it, just generates a directory if they decide to sync something.
Otherwise I say put it in a separate repo with some docs.

Few things I noticed:

• The setup instructions and env.example need to be updated.
• I don't understand the Worlds/ directory name. Feels like it should be Apps/
• I don't think Worlds/ should be git ignored, its important that people pubish source code. Ignoring could be opt-in for sophisticated people
• When I upload a file in the props, then basically delete all the code & therefor props, the config.json doesn't seem to update (it does update if I just delete the updated file in the UI though)
• If I delete an app in the repo after syncing, it still says its linked on the UI and when I unlink it, I get Failed to unlink model from development server
• If I rename the app folder in the repo, in the UI it says its unlinked, but when I try to link it again, it says Failed to link model to development server Blueprint is not defined. I think the app server crashes:

file:///Users/.../projects/hfy-peezy/src/tools/app-server.js:1490
      const changes = deepDiffCategorized(app.config, appData)
                                              ^

TypeError: Cannot read properties of null (reading 'config')
    at HyperfyAppServerHandler.handleBlueprintModified 
    ```

[ashconnell]

dang ok, gonna look at this soon, hyped!

[peezy]

I've removed all app server code from here, leaving only the changes needed on the client in order for it to be able to connect to servers. I have created another repo https://github.com/peezy/hyperfy-app-server (basically just to hide few thousand lines of code from ai in the future)

also made this https://github.com/peezy/threejs-vibe-coding-starter-kit to demonstrate how servers can be used. i feel like both of these repos should belong to hyperfy org tho

[saori-eth]

Peezy said this was ready to be looked over @ashconnell. I've tested it extensively at this point and everything works pretty well. There are things that can be improved but over all i think good start.

Let us know if there's anything you want changed or are confused about please.

[ashconnell]

Ok sounds good, will check this out tomorrow and report back

[ashconnell]

@peezy i ran into some weird syncing issues where sometimes it would sync up but not others, and i think if you duplicate an app then only one would update etc. will keep playing around with it and have a look over the code.

[peezy]

@peezy i ran into some weird syncing issues where sometimes it would sync up but not others, and i think if you duplicate an app then only one would update etc. will keep playing around with it and have a look over the code.

if you duplicate and unlink they shouldn't update, right? since its now a different blueprint.
if they are instances of the same app yea theres something wrong. i will investigate

[jb0gie]

woah