1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
# ubox MSX lib
This is a set of libraries and tools to make MSX games using the C programming
language.
There are three main components:
- **ubox**: thin wrapper around MSX 1 BIOS, focusing on Screen 2 and 32K
cartridge ROMs.
- **spman**: a simple sprite and pattern manager with flickering support.
- **mplayer**: a wrapper around Arkos 2 AKM player, supporting music and
priority based one channel sound effects.
There are also some utilities (e.g. compression), and tools to process data and
help you building your games.
The aim is making MSX games in C, without writing Z80 assembler or having a
deep knowledge of the system.
## Requirements
- GNU Make (others may work)
- a POSIX compatible environment
The [SDCC](http://sdcc.sourceforge.net/) compiler is also needed. Check the
following table for some hints on compatibility.
| Version | Compatible | Comments |
| --- | --- | --- |
| 3.9.0 | yes | - |
| 4.0.0 | yes | - |
| 4.1.0 | no | At least on Linux amd64 it generates broken Z80 code |
| 4.2.0 | yes | Needs option in `config.env`, edit the file for details |
If you want to build the example you will also need:
- python 3
- pillow
- GCC (only the C compiler)
- Disark, one of the tools distributed with Arkos Tracker 2 (download from
[Arkos Tracker 2 website](http://www.julien-nevo.com/arkostracker/))
On Windows 10, there are reports of successful builds using:
- latest version of Cygwin64 with package for gcc-core 10.2.0-1
- SDCC 4.0.0
- python 3.9.1
If you want to build the docs you will also need:
- pandoc
- python 3
- pygments
- pandocfilters
## Building
To build the libraries run:
make
After a successful build, the libraries should be in `./lib`.
The include files are ready to use in `./include`.
Add those directories in `SDCC`'s search path and you are ready to go.
Note: `make` is expected to be run from the root of the repo. The PATH env
variable will be set automatically.
### Running tests
There are tests that can be run with `make test`.
### Building the example
An example game is included with the libraries and it can be built with:
make game
After a successful build, the game ROM should be in `./bin`.
#### CAS support
Although the focus is cartridge ROMs, CAS files (and audio) is still one of the
cheapest ways of loading homebrew games on a real MSX.
Optionally, is possible to generate a CAS file of the example game running:
make game-cas
After a successful build, the game CAS should be in `./bin`.
The CAS support has some limitations:
- It requires 32K of extra RAM.
- The compressed ROM must be less than 24576 bytes.
- The loader uses the BIOS, so it won't be fast.
- Machines with disk must have it disabled (by pressing shift on boot), to
have more memory available.
Despite these limitations, it is worth considering releasing your game in CAS
format as well as cartridge ROM.
### Building the docs
The documentation is available at
[usebox.net](https://www.usebox.net/jjm/ubox-msx-lib/), so this is optional.
To build the docs run:
make docs
The reference in `HTML` format will be generated in `./docs`.
## Contributing
All contributions are welcome.
If you think you have found a bug, please submit a bug report providing some
information:
- What was expected to happen
- What actually happens
- How to reproduce the issue
Some advice if you want to make a successful contribution:
- Be cordial
- Get early feedback, specially when working on a large contribution
- Read [CONTRIBUTING](CONTRIBUTING.md)
- Check the [TODO](TODO.md) for ideas!
### Formatting
This project uses [Black](https://github.com/psf/black) to format the Python
code, and this is checked in CI.
Before submitting any code to review, ensure you have installed Black 22.1.0 and run:
black .
## Authors
This was mostly written by Juan J. Martinez during the development of
[Night Knight](https://www.usebox.net/jjm/night-knight/) and
[Uchūsen Gamma](https://www.usebox.net/jjm/uchusen-gamma/).
Other contributors:
- Pedro de Medeiros
- Your name here?
## Copying
This software is distributed under MIT license, unless stated otherwise.
See COPYING file.
**TL;DR**: the only condition is that you are required to preserve the copyright
and license notices. Licensed works, modifications, and larger works may be
distributed under different terms and without source code; this includes any game
made with the help of this software.
Credit is appreciated, but is not a legal requirement. For example: you can add
to the game's documentation a note like "This game uses ubox MSX lib".
There are some third party tools included here for convenience and are covered
by their own license or are public domain.
|
