Create my first program

Once you have installed MSXgl, you can start creating your own project.

Test template program

To validate that your MSXgl installation is correct and that you're ready to create your own project, first try to compile and run the template sample program:

• Go to projects/template (or template_msx2 if you target MSX 2 computer)
• Execute build.bat (Windows) or ./build.sh (Linux & macOS)
• Go to projects/template/emul/rom, check if template.rom exists and try it on your MSX machine or emulator.

Note: If you have configured an emulator path in projects/default_config.js, you can edit project_config.js and change "DoRun = false;" to "DoRun = true;" to allow auto-launch of the built program.

Create your project directory

Now that everything work well, let's create your own program.

You can sure start a new project from scratch, but for this example lets duplicate template (or template_msx2) directory, and rename it mygame.

Rename template.c to mygame.c.

Your new project directory should look like:

📁 MSXgl
└─📁 projects
  └─📁 mygame                Your project directory
    ├─🗎 build.bat            Launch Build tool (Windows)
    ├─🗎 build.sh             Launch Build tool (Linux)
    ├─🗎 msxgl_config.h       Library configuration
    ├─🗎 mygame.c             Your program source code
    └─🗎 project_config.js    Build tool configuration

Note: If you prefer, you can use an alternative file layout to have the MSXgl directory inside your own project directory.

Setup Build Tool

Edit project_config.js:

• Change ProjName to "mygame".
• Set Machine to the minimal version of MSX hardware you want to support for your program. Let's say "1" for .
• Set Target to your target format. Let's say ROM_32K (cartridge with a 32 KB ROM visible by the CPU on page 1 and 2).
• If you have configured an emulator path in projects/default_config.js, set DoRun to true to allow auto-launch (easier to test your program).

• Execute build.bat, check the emul/rom directory for mygame.rom and test it.

Many other build options can be defined in project_config.js. See the options list.

This is where you will be able to choose which MSX version your program is intended for (MSX 1, 2, 2+ or turbo R) and the type of program you want to create (MSX-DOS, BASIC binary, plain or mapped ROM).

Setup library

The msxgl_config.h file contains many options to configure the library to better suit your needs.

This configuration is especially useful to optimize your program and can be ignored at first. It allows for example to define which screen modes you want to support for your program so that the library adapts accordingly.

Change program content

Here it all depends on the type of game you want to make.

The following example will show you all the steps required to create a program that moves a sprite over a background on an MSX1. In the projects/samples directory you'll find numerous sample programs that will show you how to use MSXgl's various features for a variety of media.