Jump to content

Part II: Setting up a dev environment for P-Machinery


Recommended Posts

Part II: Setting up P-Machinery



In this part I'll explain how to set up the P-Machinery game framework within your development environment. I assume you have followed the instructions on "Part I: Setting up jzIntv" and that your development environment is up and ready.


1. Download P-Machinery


First off, download the latest P-Machinery distribution from the announcement post. As with jzIntv, there is no real installation; you just copy the ZIP file to wherever you want to install it, and extract the archive. I suggest you create an "intvdev" or "games" folder in your "Documents" folder. You can then use this folder as your repository of games in progress. Really, you can put it anywhere, I just like to be tidy with my files.


You'll end up with something like this:




And that's it. You're done, really. Assuming that your environment is set up as P-Machinery expects it (which was discussed in Part I), everything should be ready.


2. Assembling the demo


Let's test the P-Machinery demo, called "pmach". P-Machinery comes with two handy shell scripts to build (assemble) and run (execute) the demo. These are called, respectively, "build.sh" and "run.sh".


Open up a Terminal app window and navigate to your newly installed "pmach" directory by typing the following:

$> cd ~/Documents/intvdev/pmach


If you installed the demo in a different folder, just replace the path to the correct one.


Now, run the "build.sh" script to assemble the demo source:

$> ./build.sh


The output will contain general information of the assembled program, including how much ROM space it is using and how much Scratch and System RAM is used and available.




If everything is set up correctly, you should see the following at the bottom of the output:

              -  WARNINGS       0


If you see any errors there, go back and review your set up and make sure you followed all the steps, including those in Part I. You can also post here questions and I'll try to help as I can.


All the binary and assemblage files will be stored in the "bin" folder. Among the output generated by the "build.sh" script are the program rom (.rom and .bin), the symbol table (.sym), the memory map (.map), and the assembler listing file (.lst). These last three are useful for debugging your game.



3. Running the Demo


Now, let's try running the demo and see if it works. Just invoke the "run.sh" script from the Terminal window like this:

$> run.sh


This will invoke the jzIntv emulator with the demo. You should see the "P-MACH Test" title screen:




When you're done testing the demo, hit the F-1 key to exit the emulator.


4. Debugging P-Machinery


The "run.sh" does more than run the emulator. It also includes flags to load the symbol table and memory map into the debugger. This is useful when you want to test and debug your own games. By the default, the "run.sh" script runs jzIntv in "emulation" mode. To invoke it in "debugger" mode, just add the "-d" flag in the command-line, like this:

$> run.sh -d


The jzIntv emulator will be executed, but the emulation will be halted waiting for input from the debugger command-line. The Terminal window will show the output of the debugger with a prompt, like this:




Using the jzIntv debugger is out of the scope of this article, so you'll have to look for that elsewhere. However, you can type the "?" command for a list of all commands accepted by the debugger. When you're done debugging, just type the "q" command to quit:




5. Making your own games based on P-Machinery


So, how do you make games using P-Machinery? Well, think of the "pmach" demo as a template for games. Just make a copy of the "pmach" folder and rename it to whatever your game will be called. Then rename the file "pmach-test.asm" to whatever you'll call your ROM.


Finally, you'll have to modify the "build.sh" and "run.sh" script to use your game filename instead of "pmach-test".


And you're done. You can modify the demo source with your own code and include library and other source files as you need.



  • Like 1
Link to comment
Share on other sites

To anyone interested, the official P-Machinery site will now be hosted here. There is currently no web page there, just two files: the Mac and the Windows distribution.


They are exactly the same, the only difference is that the Mac version contains BASH shell scripts to build and run, while the Windows version contains DOS batch files for the same.


(Also, the source files contain UNIX line terminators (LF) in the Mac version, and DOS line terminators (CR+LF) in the Windows one.)


From now on, I'll keep those files up to date, so you can bookmark the URLs.



Link to comment
Share on other sites

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.
Note: Your post will require moderator approval before it will be visible.

Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

  • Recently Browsing   0 members

    • No registered users viewing this page.
  • Create New...