Launching MakeCode Arcade games as standalone app/executable

[Vegz78]

Hi Eric, and thanks for an interesting MakeCode Arcade(MCA) UWP project!

I get it to build and run for the included castle-crawler game. But unfortunately I am unable to swap out this game for other MCA games, even though I compile and download them as similar pxt64 VM files.

With reference to e.g. this forum thread, there might be quite a few people out there apart from yourself and I, that are interested in finding ways to run MCA games as standalone apps/executables.

From what I have read* and gathered from browsing the various pxt source codes and your projects, there seems to be at least 2 viable approaches to achieve this:

1. VM: Like you have done here; to compile the MCA games to VM pxt64 files, which then somehow with a native SDL interpreter should be possible to run on Windows, MacOS and Linux desktops. (I understand that this approach should also be possible on ARM and other platforms, and your UWP-approach is of course interesting, as the game would also run on XBox. But I have still not figured out how to get this SDL VM interpreter to work, and if it's like the web simulator/uf2 boot image, with a menu where you could choose among various games, or if each game needs to be bundled with its own interpreter...)
2. Native executables: Directly compile native x86_64 executables on Windows(WIn32 exe), MacOS(Mach-O) and Linux(elf). (Already solved for ARM/RPi Linux .elf, but I have not yet figured out how to do this on Windows, MacOS and Linux x86_64. But it should be possible, and maybe you know how?)

There might, of course, be other interesting approaches, like appifying online shared MCA games, integrate the online shared MCA games or downloaded .js of the games with WebView2, get the simulator to run locally etc.

However, the 2nd alternative might be the most straight forward and with the smallest storage footprint per game? In any case, both approaches are very interesting to explore further, with many different applications and use cases.

On a local pxt server, I have managed to compile the following:

• binary.asm files with various contents(what looks like the IR(VM?) bytecode or ARM assembly, but I am unable to assemble)
• binary.js, which I understand is the file type that the web simulator runs
• binary.pxt64 which I understand is the VM bytecode
• binary.uf2 for all the listed handheld MCU hardware
• binary.elf for ARM/RPi native executable
• A dockercross folder with what seems to be the C++ source code for pxt.dll(or the game with pxt.dll?), which I am unable to compile yet, but I suspect might be possible to compile somehow with multiarch crossbuild.

But I have not yet found a way to get pxt to output x86_64 executables for Windows, MacOS or Linux, nor a ready compiled pxt.dll.

Would you be interested to please help us make this black magic work, document the various approaches, and maybe find the documentation for win32 binaries etc.?

Sources:

• https://www.microsoft.com/en-us/research/publication/static-typescript/
• https://www.microsoft.com/en-us/research/publication/makecode-and-codal-intuitive-and-efficient-embedded-systems-programming-for-education-jsa/
• https://www.infoq.com/presentations/makecode/

[Vegz78]

Is this how you built pxt.dll for this project?: https://github.com/eanders-ms/pxtdll-vs-build

[eanders-ms]

haha, no that was an entirely different experiment to get pxt.dll building in visual studio. I wanted to step through it in the debugger.

Native executables for Windows, Mac, and Linux can be built without the need for a UWP layer, but I just tried it and it has a couple regressions. One is a minor code issue, but the other I'm not sure about. The app starts, but encounters a "validation error" on the pxt64 payload. I think we'll need @mmoskal's help to resolve it!

[eanders-ms]

I want to make sure to note that MakeCode's ability to generate native executables was itself an experimental direction that wasn't pursued. So while the capability is still there, it isn't a supported feature. Consequently, it has seen some bit rot.

[Vegz78]

Ok, thanks for the feedback and looking into this!

I only wish there was some way I could find out or read about how to myself compile native executables - with and without the UWP layer - of the games and the pxt.dll, so I could follow and maybe contribute after a while... ;-) Any hints?

But isn't the pxt64 payload the IR or bytecode for the VM? What about compiling natively directly to Windows, Mac and Linux, like with hw=rpi&compile=rawELF for the RPi, or for other microcontrollers?

[eanders-ms]

The way I build pxt.dll is fairly involved. Maybe there's a simpler way, but this works for me:

0. First, note that the final executable will not display the game due to a regression that came in with support for ESP32. Knowing this, if you wish to continue...
1. Install Docker if necessary: https://docs.docker.com/get-docker.
2. Setup to build and run Arcade locally. Instructions here: https://github.com/microsoft/pxt-arcade#local-dev-setup
3. Run Arcade locally. After the page loads, add this URL parameter: ?ws=fs. This tells Arcade to use the "filesystem" workspace. In this mode, Arcade will save a copy of your projects to a local folder: pxt-arcade/projects. This is in the pxt-arcade repo's hierarchy. Note: ensure you are not signed in to Arcade. This feature doesn't work in the signed-in state.
4. Open a project in the editor. This will trigger a save. Verify it was saved to the projects folder.
5. Open a command shell and navigate to your locally saved project (pxt-arcade/projects/<your project>).
6. Set these three environment variables (pxt help explains them):

   PXT_ASMDEBUG=1
   PXT_FORCE_LOCAL=1
   PXT_RUNTIME_DEV=1

7. Run pxt install
8. Run pxt build. At this point you should see a local build happening, with lots of warnings :). You will eventually get a build error having to do with uint32_t vs uint64_t. To fix this, just change the types to uint64_t.
9. Run the build again. It will produce SDL binaries for Win32, Linux, and macOS. Find them in pxt-arcade/projects/<your project>/built/dockercross/bld*
10. For Win32, copy pxt.dll and pxt-vm-sdl.exe from bld-x86_64-w64-mingw32 to the built folder (where binary.pxt64 exists).
11. Run it: pxt-vm-sdl.exe ./binary.pxt64. A window will appear with the title MakeCode Arcade64, but it's contents will be blank. This window should render the game, but doesn't due to the recent regression. My knowledge breaks down at this point and can't recommend a fix.

Big disclaimer: This is not a supported feature of MakeCode.

[eanders-ms]

Edited to correct the url parameter. It should have been ?ws=fs.

[Vegz78]

Amazing! Thanks for the instructions and I am looking forward to trying them out!

[eanders-ms]

Good luck! Let me know if you hit any issues. I wrote the steps from memory, so it's entirely possible I missed something :)