Hello world tutorial

This tutorial will guide you through all the necessary steps to make a NeoGeo romset which displays the text "Hello world !". It is written for Windows but all the necessary tools have equivalents on MacOS and Linux.

The programming language used is 68k assembly, but good knowledge of it is not needed as all instructions will be detailed.

Setting up a minimal development environment

• Download the latest MAME binaries from [mamedev.org]. Extract the zip contents to a folder such as "C:/MAME/".
• To run NeoGeo software with MAME, you will need the dumps of the various ROMs which are part of the system. You can find them as a pack called neogeo.zip (various forms, more or less complete). The files needed are 000-lo.lo (64KiB, the LO ROM), sm1.sm1 (128KiB, the M1 ROM for sound), sp-s2.sp1 (128KiB, the system ROM) and sfix.sfix (128KiB, the SFIX ROM). They will have to be copied to the "C:/MAME/roms/neogeo/" folder for them to be recognized by MAME. Like original games these ROMs are copyrighted, so you won't find them here.
• As a base, find and download a Super Sidekicks romset (ssideki.zip) and extract it to "C:/MAME/roms/ssideki/". Make sure that the following files are present and make sure they are named correctly (MAME is picky about file names and extensions):
  • 052-c1.c1 and 052-c2.c2 (C ROM pair, sprite graphics)
  • 052-m1.m1 (Z80 code, we won't mess with that)
  • 052-p1.p1 (68k code, that's what we'll replace)
  • 052-s1.s1 (S ROM: fix graphics, we'll use it)
  • 052-v1.v1 (V ROM: sound, won't touch that either)
• Write a short batch file to start MAME easily with the right parameters. Create a new text file and add these lines:

mame -debug -nofilter -window ssideki
pause

Save it with the .bat extension in "C:/MAME/" and run it. MAME should open the emulation window and its debugger. Don't be scared, just highlight the debugger window and press F5 to see if Super Sidekicks starts in the main window. If the romset is bad, the missing and/or invalid files will be shown in the command line prompt (bad checksum, missing files...). When the game runs correctly, close the debugger and the emulation window.

• Download [the macro assembler AS (ASW)] and this zip file. There is no installation required, just extract those files to a folder like "C:/neogeo/asw/".
• For the purpose of this tutorial, Notepad can be used as a code editor. Make a folder for this project such as "C:/neogeo/helloworld/".
• Write a batch file in this folder to make ASW assemble your code. Create a new text file with the following contents:

@echo off
c:\neogeo\asw\asw main -L -quiet
c:\neogeo\asw\p2bin main -r $000000-$01FFFF
c:\neogeo\asw\flip main.bin 052-p1.bin
c:\neogeo\asw\pad 052-p1.bin 524288 255
copy 052-p1.bin c:\mame\roms\ssideki\052-p1.bin

And save it as "make.bat" in the "C:/neogeo/helloworld/" folder.

ASW assembles your code, p2bin makes the P ROM with the right size ($1FFFF = 128KiB), flip.exe flips bytes in pairs (byteswapping) because P ROMs have to be that way, pad.exe fills up the P ROM with "$FF" (255) bytes up to 512KiB to match the original ssideki P ROM size and make MAME happy, and it's finally copied in place of the original Super Sidekicks P ROM.

Be aware that only the P ROM file is replaced, all graphics, musics and sounds will still be those from Super Sidekicks.

Now that you have everything to assemble and run the ROM, you can start coding.

The code

• Go to the 68k ASM defines page, copy everything, paste it in a new text file and save it as "regdefs.asm" in "c:/neogeo/helloworld/". This allows you to use register names in place of their addresses (easier to remember). For example, instead of writing

  $300001

  in your code, you'll be able to write

  REG_DIPSW

  instead and ASW will take care of translating that to $300001.
• Create a new text file and add the following lines:

    cpu 68000
    supmode on
    INCLUDE "regdefs.asm"

These aren't assembly instruction but directives that only ASW will understand. cpu 68000 indicates what CPU we're writing code for (Motorola 68000), supmode on indicates that the code will run in supervisor mode (allows us to use special instructions, the NeoGeo always runs in supervisor mode), and INCLUDE tells ASW to take a look in our previous "regdefs.asm" file. Save this file as "main.asm" in "c:/neogeo/helloworld/".

Formalities

For the "cartridge" to be recognized by the system ROM and launched, header data must be present. Copy the minimal header to a new "header.asm" file.

This will also set up the v-blank interrupt vector to a label called VBLANK.

A bit of thinking

To display the "Hello world !" text, there are basically two methods:

• Use sprites (one sprite for each letter, for example)
• Use the fix layer (one tile per letter)

To avoid the need to edit the sprite ROMs and draw a font, we will use the one that is already stored in the ssideki's fix ROM (052-s1.bin).

If you look at the contents of a typical S ROM (like on this page), you will see that the first bank ($100) of tiles contains a 8x8 pixels character set, which is often customized for each game. The Super Sidekicks one uses color gradients, so we will use the 8x16 pixels alphabet instead, which is simpler (2 colors). It is found in the next two tile banks (tiles $100 to $2FF).

As shown in the SFIX tileset reference, bank 1 (tiles $100 to $1FF) contains the upper tiles (the top of the letters), and bank 2 (tiles $200 to $2FF) contains the lower tiles (the bottom of the letters).

By mapping those tiles correctly on the fix map, text can be displayed.

Note that there is a named MESS_OUT which purpose is to simplify text writing to the fix layer. For the purpose of this tutorial we'll do it the hard way, without using this call.

Cleaning everything up

Before writing tile numbers to the fix map, we want to make sure it's cleared. For this, we will fill it with tile $FF (which is filled with color 1). A loop is used to fill in the 40*32 fix map:

move.l   #(40*32)-1,d0
move.w   #FIXMAP,REG_VRAMADDR
.clearfix:
move.w   #$00FF,REG_VRAMRW
move.b   d0,REG_DIPSW
dbra     d0,.clearfix

Register D0 is used as the loop counter, which will be decremented each iteration. The count must be 1 less because DBRA branches again when D0=0. Keep in mind that the VRAM is accessed only by words, and that the fix map also holds the palette number for each tile. So we need to write $00FF (palette 0, tile $0FF). The byte write to REG_DIPSW kicks the watchdog, this has to be done regularly otherwise the NeoGeo will reset.

Now that the fix is cleared, the palette needs to be set up. We'll use the first 2 colors of palette 0. The first color is the background, the second is the text.

move.w   #BLACK,PALETTES
move.w   #WHITE,PALETTES+2

Writing the text

The text can now be mapped to the fix map.

• To be continued...