Part One : The introduction

A couple of years ago I started developing games for the ZX Spectrum using MPAGD (version 0.7.10). I found it fairly easy to use, but not without its quirks. About a dozen games later (not all of which were published) and a post on the MPAGD support forum was flagging a problem building an Enterprise version of a game. I'd not really looked at the Enterprise at this point, but I am always keen to help and test things out if able.

From this, I learnt that the AGD engine supplied with MPAGD was a beta version and they needed people with AGD knowledge to write games and try things out, which would lead to identifying (and fixing) bugs and adding extra levels of support. This would then make it easier for the many developers of Spectrum games (using MPAGD/AGD) to transfer their games to the Enterprise.

A few revisions of the code on, and Noel has created a solid implementation of the engine and, with the latest update, added support for common Spectrum Music engines and tools (Beepola, MPAGDMusicizer PT3).

Part Two : Getting started.

Software

In the first instance you will need a copy of MPAGD. This can be downloaded from: Jonathan Cauldwell's itch.io page. At time of writing the current version is 0.7.10, however I've seen that Jonathan is working on adding support for additional machines and a new version may be on the horizon. (If you've already created a game on the Spectrum using MPAGD, you'll have this already!)

The second thing you will need will be the updated code for the Enterprise engine. At time of writing, this has only been shared via the MPAGD support forum. If it becomes available officially (either as part of the MPAGD codebase or as a stand-alone enhancement) I'll update this page with the details. Essentially this will replace the files in the MPAGD "Suite EP" folder and includes a new version of the AGD engine for the Enterprise, a new version of the CompilerEP.EXE and a lot of assembler code that can be used to add Spectrum music to your game.

I have been given permission to share a link to the updated code for the Enterprise Compiler and Engine : Google Drive Link

Download that ZIP file and extract it into the main MPAGD folder. The contents of the ZIP archive will replace the previous SUITE EP folder and the build-ep.bat file.

Emulator Configuration

MPAGD comes bundled with an Emulator for the Enterprise called: EP128-2.0.11this is a powerful emulator, but it isn't always obvious how to make it work. (I had to reach out for some advice!)

You will find the emulator in the Suite EP\EP128-2.0.11 subfolder and it can be started by typing ep128emu.exe -no-opengl at the command line.

After starting the emulator, the first thing you will need to do is ensure it is configured correctly.

From the main menu, select: Machine, Configure

In the General section, ensure that "Enable virtual File I/O" is selected. 

Then select: Memory This is where we tell the emulator which ROMs you are going to need to use, and how much memory the Enterprise will have on board.

Make sure you have set the RAM Size in Kilobytes to 128.
(It may be 64K by default, but this causes the RAM to be contended with the Graphics and can cause slow-down in your games).

Make sure you have your ROM images set to:

00 - exos2.1.rom
04 - basic21.rom
10 - epfileio.rom

These may take a couple of slots, but don't worry. That is normal. The ROMs should be fairly self explanatory. The EXOS is the Operating System, the BASIC is the BASIC programming language and the EPFILEIO is a special ROM that allows you to load files directly from the Host PC's disk, rather than having to use a disk or tape image.

You will need to set the default location on the Host PC disk for EPFILEIO.

From the main menu, select Options and then Set working Directory

You will want to point this to the files subfolder. ( Suite EP\EP128-2.0.11\files )
This is where your exported games will need to go.

The Emulator should automatically save these settings.
Once they are in place, you are free to close the emulator for the time being.

Part Three : Your first MPAGD game converted to the Enterprise.

Once all the configuration is sorted for the emulator, you should be ready to convert your first game to the Enterprise. To show and test the process, you are going to create the most basic of games. Open MPAGD. Create a new project. Select the machine to be Spectrum Standard or Spectrum ULAplus. (You do not select Enterprise. At the moment if you create a project specifically targeting the Enterprise, it will fail to build with a "DEFINEPALETTE requires 64 RGB definitions on line 152:" error).

You then create a simple sprite, a simple screen and register a sprite position for the Player respawn location. If you like, define your favourite keys for controlling your sprite. (All of these options are under Editor on the main menu)

You then can use the Script Generator tool to set the basic scripts for movement. Just make the player sprite have the Platformer set of scripts, and have everything else (except for Other Events) left as (existing). Other events set to "Auto Generate" (This will give you the intro menu which will allow you to redefine keys and start the game). If you've made a few MPAGD games already, you will be familiar with all this.

Save your project. I find one of the quirks of MPAGD is you then have to reload the project.

Build your game and confirm it works. It will load up a Speccy emulator window and it should autoload the game.

Now you've confirmed the game works, you need to convert it to the Enterprise.

Export your game; you will not need the TAP image. All you are looking for is the AGD file that gets generated.

I will call my game ETUT001.AGD as it's the Enterprise Tutorial 001. When it comes to naming your game for the Enterprise, you need to use the old 8.3 naming convention (8 characters for the title then a 3 letter file extension). The Enterprise will not support long filenames and could experience problems if you try to load a game with a long name.

You then need to go to the command line; you can do this as a regular user. You do not need admin permissions.

Go to the folder MPAGD is installed in. In my case it is: C:\DEV\V0.7.10-old5\V0.7.10

If you look at what is in this folder, you will see there are a lot of folders that start SUITE. These are the specific build engines and tools for each of those machines. For the Enterprise you will need to change into the SUITE EP folder. So, in my setup, this will be:

CD "C:\DEV\V0.7.10-old5\V0.7.10\SUITE EP"

In the Suite EP folder there are up to 6 folders. (6 in the latest build of the engine/ compiler code). These are

1. AGD
   The AGD folder contains the CompilerEP.exe program that takes your AGD code and turns it into z80 assembler. It also contains the EngineEP.asm for the Enterprise.
2. AGDsources
   This folder contains the Source AGD files for your games. When you export a game from MPAGD it will place an AGD file in this location for your game. Because you are exporting a Spectrum game and are going to convert it, the AGD file you will want is in the SUITE ZX\AGDsource folder.
3. Convert
   This contains a tool to extract an AGD file from a snapshot. I've not used this and don't expect to look at it in these tutorials. But it exists and is here if you need it.
4. EP128-2.0.11
   This is the location for the EP128-2.0.11 emulator you configured earlier.
5. Sjasm
   This folder contains the Sjasm z80 compiler which takes the assembler code generated by the CompilerEP.exe program and turns it into your game. It will output a .COM and a .PRG file which can be loaded into the emulator.
6. Sound_SRC
   This folder holds two subfolders. One contains a selection of Beepola Tune engines converted to work on the Enterprise. The other contains a port of the AY-3-8912 PT3 engine used in MPAGDMusicizer games to allow Spectrum 128K music to be played during the game.
   
   These two folders only exist in the latest builds and will be covered in future tutorials which will look at adding Spectrum music to your Enterprise games.

You now need to copy your AGD file you exported earlier to the AGDsources folder. It will be in the SUITE ZX\AGDsource folder.

Once you have done this, you can use the build.bat script to create your game. Type build.bat and the filename of your AGD code, without the AGD extension.

As you can see here, if it all succeeds you will have no errors and the emulator will automatically start.

Selecting 1 will start the game and you will be able to move your little sprite around as expected.

It is as simple as that. You have gone from having a Spectrum game to having an Enterprise game.

There are a couple of changes you will need to make to the AGD code that is generated when you export. The Enterprise does not have a Sinclair Joystick or a Kempston one. Instead it has a built in joystick and an option for up to two external joysticks. You should edit your AGD menu code to say Joystick1 and Joystick2 rather than Sinclair and Kempston.

It's easy enough to do this in notepad or any "plain text" file editor. (notepad++ is a good alternative)

type: notepad AGDsources\ETUT001.AGD

Changing these two lines and then running through the build process again gives you:

And that is it. You have converted (a very basic) game to the Enterprise.

An additional note. If you do not want to copy your AGD file from the SUITE ZX\AGDsource to the SUITE EP\AGDsources folder, you can place it in the main MPAGD folder. (In my instance this is: C:\DEV\V0.7.10-old5\V0.7.10 ) and then if you run "build-ep.bat AGDFILENAME" from that location it will compile the game and start the emulator for you.

The advantage of doing it this way is that you are able to pass additional parameters to the compiler, such as -a for adventure mode or -l for a loading screen. 

My preferred method is to work in the SUITE EP folder, but both methods work well and are options.

My next tutorial will look at adding Spectrum sounds and music to the game.

Part Four : The aftermath

Things to be aware of when converting your games:

1. On the ZX Spectrum, there is an amount of memory following the screen memory. If you accidentally write into this area (e.g. by printing something outside of the screen memory, eg. Line 24; the Spectrum usually doesn't complain. If you do this on the Enterprise, it will corrupt your game. Ensure your code is only writing to valid screen locations.
2. When you are defining the default keys in MPAGD for your Spectrum game, the SHIFT key does not appear to translate to the Enterprise version of the game. If you allow keys to be redefined, SHIFT can be selected as a valid key so it must be something relating to the translation of the AGD representation of SHIFT that is not recognised by the Enterprise. (This is being checked. It might also be that the Enterprise has two SHIFT keys and they are recognised as different keys whereas the Spectrum has a SHIFT and a SYMBOL SHIFT) This has been resolved in the latest version.
3. If you have any USER.ASM code it will need to be converted. Code for the Beepola engines and AY Tunes has already been created, but anything additional will need to be converted. (It may be a simple case of pointing the code at different memory locations depending on what the USER.ASM code is doing).
4. The Enterprise is emulating the ZX Spectrum's display mode. This means attribute clash and behaviours should be the same. However there is no FLASH on the Enterprise. For most games, this will not be a problem.

Issues with V0.7.10 version of the Enterprise MPAGD Engine and enhancements

If you are using the default engine as supplied with MPAGD v0.7.10, the following issues could exist. These have been fixed in the latest version of the engine and compiler. There may be others, but I have lost track of everything that has been fixed. Pretty much as soon as a bug has been found, Noel has identified and fixed it.

1. the TICKER command does not work correctly. Fixed in latest version.
2. directions are incorrect on the STAR command. Fixed in latest version.
3. default direction for sprites might not be set. Fixed in latest version.
4. menu / inventory command may not work correctly. Fixed in latest version.
5. Shift key not recognised (if you pre-define it in MPAGD). Fixed in latest version.

The following enhancements have been made.

1. Support for Spectrum "Border sounds" (A common technique for making sound fx on the Spectrum is to cycle a number of high value border colours to make a variety of sounds). Support for this has been added.
2. Support for Beepola Engines.
3. Support for AY Tunes in Pro tracker 3 PT3 format.
4. Support for including a loading screen before the game starts.

(There may be other fixes and enhancements too which I am not recalling at this time).

These improvements and enhancements have all been down to the dedication and hard work of Noel Persa who has been fixing bugs as they've been found and has looked and worked at converting many of the Spectrum MPAGD game features to the Enterprise version of the engine. Without all this hard work, none of this would be possible.