devkitSMS

https://github.com/sverx/devkitsms
Admin
devkitSMS is a collection of tools and code for SEGA Master System, Game Gear, SG-1000/SC-3000, and...
Tokens:60,454
Snippets:395
Trust Score:9.1
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Example assets2banks.cfg file with all directives

Source: https://github.com/sverx/devkitsms/blob/master/tools/assets2banks/README.md

Complete configuration example for assets2banks.cfg. Comment lines start with #, asset groups are enclosed in braces, and asset entries are followed by directives prefixed with ':'. Directives shown include :format, :overwrite, :alias, :modify, :ignore, :text, :discard, :replace, :segment, :header, and :append. Assets not listed in the config are handled as ungrouped and without special attributes.

```text
# assets2banks.cfg example file
# this is a comment

# next line starts an asset group:
{ 
asset1 (tiles).bin 
asset1 (tilemap).bin 
:format unsigned int 
# 'asset1 (tilemap).bin' will be a const unsigned int array
}
# asset group complete

# other assets (ungrouped) 
asset2 (palette).bin
:overwrite 0 0x00
:alias BGpalette
# the zero-indexed element of the array will be set to 0x00, and the array will be called BGpalette instead of asset2__palette__bin

asset2 (tiles).psgcompr
asset3 (tilemap).bin 
:format unsigned int
:modify OR 0 16 0x1000
# 'asset3 (tilemap).bin' first 16 elements (starting from 0) will be ORed with 0x1000 bit mask

my_notes.txt  # I keep track of some important information in here!
:ignore
# 'my_notes.txt' will be ignored

asset4.bin
:format unsigned int
:overwrite 32 128 0x010a 0x01FF 0x0123
# 'asset4.bin' 128 elements starting from array[32] will be set to the values listed
# (values list will be reitered until 128 array elements are replaced)

some_LUT.csv
:text
# this is a CSV file that will be parsed into an array
:discard 0 32
:discard 200 0
# the first 32 elements of the array will be discarded, and the same to all the elements from the 200th onward
:replace 0 0xFF
# any element in the array equal to 0 will become 0xFF

somedata.bin
:segment skip 32
:modify AND 0xFE
:header 0xF5 0xC9
:append 0x00
# takes 'somedata.bin' skipping the first 32 bytes from it, clears the last bit of each element, prepends a 2 bytes header 0xF5 0xC9 and then appends one 0x00 byte to it
```

--------------------------------

### Start banks from a different number with --firstbank

Source: https://github.com/sverx/devkitsms/blob/master/tools/assets2banks/README.md

Using --firstbank=6 starts the bank numbering from 6 instead of the default 2, useful when other code banks need to be allocated before data banks.

```bash
assets2banks assets --firstbank=6
```

--------------------------------

### void PSGSFXPlay(unsigned char *sfx, unsigned char channels)

Source: https://github.com/sverx/devkitsms/blob/master/PSGlib/README.md

Starts playing a sound effect (SFX).

```APIDOC
## void PSGSFXPlay(unsigned char *sfx, unsigned char channels)

### Description
Starts playing a sound effect (SFX).

### Parameters
- **sfx** (unsigned char *) - Required - Pointer to the SFX data.
- **channels** (unsigned char) - Required - Channels to use for the SFX.

### Returns
None.
```

--------------------------------

### SG_waitForVBlank

Source: https://github.com/sverx/devkitsms/blob/master/SGlib/README.md

Waits until the next vBlank starts.

```APIDOC
## SG_waitForVBlank

### Description
Waits until the next vBlank starts.

### Method
Function

### Signature
void SG_waitForVBlank(void)

### Parameters
None

### Returns
None
```

--------------------------------

### Example usage of :segment

Source: https://github.com/sverx/devkitsms/blob/master/tools/assets2banks/README.md

Shows three assets with different :segment configurations: import first 1024 bytes, import 128 bytes after skipping 256, and import whole file after skipping 32 bytes.

```plaintext
blob1.bin
:segment 1024

blob2.bin
:segment 128 skip 256

blob3.bin
:segment skip 32
```

--------------------------------

### Example text data file for :text attribute

Source: https://github.com/sverx/devkitsms/blob/master/tools/assets2banks/README.md

Shows a valid text file for the :text attribute. Values are parsed into an array; this example produces values from -6 to 25. Demonstrates accepted formats: hex, negative, comments, various separators, and leading zeroes.

```plaintext
# this is some data in text form

-6 -5 -0x0004 ( -0x03 -0x2 -1    # hex and/or negative is also supported
{0, 1, 2, 3, 4}

[5  6  7  8  9]                  # note that no specific separators or brakets are needed
10,,,11,,,12,,,13

[14] 15 [16] 17 ]]               
018; 019; {020}; (021);          # leading zeroes in decimal values are accepted too
0x16, 0x17, 0x18         0x19
```

--------------------------------

### void PSGSFXPlayLoop(unsigned char *sfx, unsigned char channels)

Source: https://github.com/sverx/devkitsms/blob/master/PSGlib/README.md

Starts playing a looping sound effect (SFX).

```APIDOC
## void PSGSFXPlayLoop(unsigned char *sfx, unsigned char channels)

### Description
Starts playing a looping sound effect (SFX).

### Parameters
- **sfx** (unsigned char *) - Required - Pointer to the SFX data.
- **channels** (unsigned char) - Required - Channels to use for the SFX.

### Returns
None.
```

--------------------------------

### void PSGPlayNoRepeat(void *song)

Source: https://github.com/sverx/devkitsms/blob/master/PSGlib/README.md

Starts playing a PSG tune and stops at the loop point (no repeat).

```APIDOC
## void PSGPlayNoRepeat(void *song)

### Description
Starts playing a PSG tune and stops at the loop point (no repeat).

### Parameters
- **song** (void *) - Required - Pointer to the song data.

### Returns
None.
```

--------------------------------

### Combine options: --firstbank, --singleheader, --compile

Source: https://github.com/sverx/devkitsms/blob/master/tools/assets2banks/README.md

Combines multiple options to generate compiled REL files starting from bank 6 and a single header file named assets.h.

```bash
assets2banks assets --firstbank=6 --singleheader=assets.h --compile
```

--------------------------------

### unsigned char PSGSFXGetStatus(void)

Source: https://github.com/sverx/devkitsms/blob/master/PSGlib/README.md

Gets the current status of the SFX.

```APIDOC
## unsigned char PSGSFXGetStatus(void)

### Description
Gets the current status of the SFX.

### Parameters
None.

### Returns
- **unsigned char** - The current status of the SFX.
```

--------------------------------

### Compile and link multi-bank ROM with SEGA ROM paging

Source: https://github.com/sverx/devkitsms/blob/master/README.md

Compile, link, and build a ROM using more than 48 KiB via SEGA ROM paging. Put data in separate .c files per 16 KiB bank starting from bank2, compile each with a different CONST segment name (e.g., BANK2, BANK3). Link with custom parameters placing banks at 0x8000 + banknumber×2^16 (BANK2 at 0x28000, BANK3 at 0x38000). Proper crt0 goes first, bank .rel files last in ascending order. Use SMS_mapROMBank(n) or SG_mapROMBank(n) to map banks; code should be restrained to the first 32 KiB.

```bash
  sdcc -c -mz80 --constseg BANK2 bank2.c
  sdcc -c -mz80 --constseg BANK3 bank3.c

```

```bash
  sdcc -c -mz80 --peep-file peep-rules.txt your_program.c

```

```bash
  sdcc -o your_program.ihx -mz80 --no-std-crt0 --data-loc 0xC000 -Wl-b_BANK2=0x28000 -Wl-b_BANK3=0x38000 crt0_sms.rel your_program.rel SMSlib.lib bank2.rel bank3.rel

```

```bash
  makesms your_program.ihx your_program.sms

```

--------------------------------

### Generate C source files from assets

Source: https://github.com/sverx/devkitsms/blob/master/tools/assets2banks/README.md

Basic usage that creates bank*n*.c and bank*n*.h files (starting from n=2) from the files in the specified asset folder. Each array is named from the original filename with spaces, periods, and brackets replaced by underscores.

```bash
assets2banks assets
```

--------------------------------

### void PSGPlay(void *song)

Source: https://github.com/sverx/devkitsms/blob/master/PSGlib/README.md

Starts playing a PSG tune and loops it forever. The song parameter points to the song data.

```APIDOC
## void PSGPlay(void *song)

### Description
Starts playing a PSG tune and loops it forever.

### Parameters
- **song** (void *) - Required - Pointer to the song data.

### Returns
None.
```

--------------------------------

### unsigned char PSGGetStatus(void)

Source: https://github.com/sverx/devkitsms/blob/master/PSGlib/README.md

Gets the current status of the tune.

```APIDOC
## unsigned char PSGGetStatus(void)

### Description
Gets the current status of the tune.

### Parameters
None.

### Returns
- **unsigned char** - The current status of the tune.
```

--------------------------------

### void PSGPlayLoops(void *song, unsigned char loops)

Source: https://github.com/sverx/devkitsms/blob/master/PSGlib/README.md

Starts playing a PSG tune and loops it the specified number of times.

```APIDOC
## void PSGPlayLoops(void *song, unsigned char loops)

### Description
Starts playing a PSG tune and loops it the requested amount of times.

### Parameters
- **song** (void *) - Required - Pointer to the song data.
- **loops** (unsigned char) - Required - Number of times to loop the tune.

### Returns
None.
```

--------------------------------

### SG_getKeyboardJoypadReleased

Source: https://github.com/sverx/devkitsms/blob/master/SGlib/README.md

Gets the keys released on the keyboard virtual joypad.

```APIDOC
## SG_getKeyboardJoypadReleased

### Description
Gets the keys released on the keyboard virtual joypad.

### Method
Function

### Signature
unsigned int SG_getKeyboardJoypadReleased(void)

### Parameters
None

### Returns
unsigned int - The keys released on the keyboard virtual joypad.
```

--------------------------------

### SG_getKeyboardJoypadStatus

Source: https://github.com/sverx/devkitsms/blob/master/SGlib/README.md

Gets the current status of the keyboard virtual joypad.

```APIDOC
## SG_getKeyboardJoypadStatus

### Description
Gets the current status of the keyboard virtual joypad.

### Method
Function

### Signature
unsigned int SG_getKeyboardJoypadStatus(void)

### Parameters
None

### Returns
unsigned int - The current status of the keyboard virtual joypad.
```

--------------------------------

### void PSGPlayNoRepeat(void *song, unsigned char bank) [Multibank]

Source: https://github.com/sverx/devkitsms/blob/master/PSGlib/README.md

Starts playing a PSG tune and stops at the loop point, with multibank support. Only available when compiled with PSGLIB_MULTIBANK.

```APIDOC
## void PSGPlayNoRepeat(void *song, unsigned char bank) [Multibank]

### Description
Starts playing a PSG tune and stops at the loop point, with multibank support. Only available when compiled with PSGLIB_MULTIBANK.

### Parameters
- **song** (void *) - Required - Pointer to the song data.
- **bank** (unsigned char) - Required - Initial bank number for the song data.

### Returns
None.
```

--------------------------------

### Example usage of :alias

Source: https://github.com/sverx/devkitsms/blob/master/tools/assets2banks/README.md

Generates an array named _sprites_ even though the asset file is named sprites_final_Final_FINAL.bin.

```plaintext
sprites_final_Final_FINAL.bin
:alias sprites
```

--------------------------------

### Set next background color index with SMS_setNextBGColoratIndex

Source: https://github.com/sverx/devkitsms/wiki/Advanced

Macro to set the starting index for updating background palette colors.

```c
SMS_setNextBGColoratIndex(i);
```

--------------------------------

### Multibank compile commands for PSGlib

Source: https://github.com/sverx/devkitsms/blob/master/PSGlib/how to build this.txt

Compiles the PSGlib sources with the PSGLIB_MULTIBANK define, producing .rel files with the _MB suffix. Use this for multibank ROM setups.

```shell
sdcc -c -mz80 --max-allocs-per-node 100000 -D PSGLIB_MULTIBANK -o PSGlib_MB.rel PSGlib.c
sdcc -c -mz80 --max-allocs-per-node 100000 -D PSGLIB_MULTIBANK -o PSGAttenuation_MB.rel PSGAttenuation.c
sdcc -c -mz80 --max-allocs-per-node 100000 -D PSGLIB_MULTIBANK -o PSGPlayLoops_MB.rel PSGPlayLoops.c
sdcc -c -mz80 --max-allocs-per-node 100000 -D PSGLIB_MULTIBANK -o PSGRestoreVolumes_MB.rel PSGRestoreVolumes.c
sdcc -c -mz80 --max-allocs-per-node 100000 -D PSGLIB_MULTIBANK -o PSGResume_MB.rel PSGResume.c
```

--------------------------------

### Generate a single header file with --singleheader

Source: https://github.com/sverx/devkitsms/blob/master/tools/assets2banks/README.md

Using --singleheader generates a single assets2banks.h header file instead of separate headers for each bank. Note that the example output mentions .rel files, but the description says it creates bank*n*.rel files.

```bash
assets2banks assets --singleheader
```

--------------------------------

### void PSGPlay(void *song, unsigned char bank) [Multibank]

Source: https://github.com/sverx/devkitsms/blob/master/PSGlib/README.md

Starts playing a PSG tune and loops it forever, with multibank support. Only available when compiled with PSGLIB_MULTIBANK.

```APIDOC
## void PSGPlay(void *song, unsigned char bank) [Multibank]

### Description
Starts playing a PSG tune and loops it forever, with multibank support. Only available when compiled with PSGLIB_MULTIBANK.

### Parameters
- **song** (void *) - Required - Pointer to the song data.
- **bank** (unsigned char) - Required - Initial bank number for the song data.

### Returns
None.
```

--------------------------------

### void PSGPlayLoops(void *song, unsigned char bank, unsigned char loops) [Multibank]

Source: https://github.com/sverx/devkitsms/blob/master/PSGlib/README.md

Starts playing a PSG tune and loops it the specified number of times, with multibank support. Only available when compiled with PSGLIB_MULTIBANK.

```APIDOC
## void PSGPlayLoops(void *song, unsigned char bank, unsigned char loops) [Multibank]

### Description
Starts playing a PSG tune and loops it the requested amount of times, with multibank support. Only available when compiled with PSGLIB_MULTIBANK.

### Parameters
- **song** (void *) - Required - Pointer to the song data.
- **bank** (unsigned char) - Required - Initial bank number for the song data.
- **loops** (unsigned char) - Required - Number of times to loop the tune.

### Returns
None.
```

--------------------------------

### Overwrite multiple elements

Source: https://github.com/sverx/devkitsms/blob/master/tools/assets2banks/README.md

Replaces length array elements starting at start with the listed values, repeating them if needed. Accepts decimal or 0x-prefixed hex values.

```plaintext
:overwrite <start> <length> <value> [<value>[...]]
```

--------------------------------

### Create PSGlib static libraries with sdar

Source: https://github.com/sverx/devkitsms/blob/master/PSGlib/how to build this.txt

Creates the four static libraries (default, multibank, noSFX, ColecoVision) from the corresponding .rel files using sdar.

```shell
sdar r PSGlib.lib PSGlib.rel PSGAttenuation.rel PSGPlayLoops.rel PSGRestoreVolumes.rel PSGResume.rel
sdar r PSGlib_MB.lib PSGlib_MB.rel PSGAttenuation_MB.rel PSGPlayLoops_MB.rel PSGRestoreVolumes_MB.rel PSGResume_MB.rel
sdar r PSGlib_NOSFX.lib PSGlib_NOSFX.rel PSGAttenuation_NOSFX.rel PSGPlayLoops_NOSFX.rel PSGRestoreVolumes_NOSFX.rel PSGResume_NOSFX.rel
sdar r PSGlib_CV.lib PSGlib_CV.rel PSGAttenuation_CV.rel PSGPlayLoops_CV.rel PSGRestoreVolumes_CV.rel PSGResume_CV.rel
```

--------------------------------

### Create SGlib_CV.lib archive

Source: https://github.com/sverx/devkitsms/blob/master/SGlib/how to build this.txt

Create the SGlib_CV.lib archive for ColecoVision, combining the ColecoVision-specific .rel files with the shared ones (spriteClip, zx7, debug).

```bash
sdar r SGlib_CV.lib SGlib_CV.rel SGlib_spriteClip.rel SGlib_zx7.rel SGlib_zx7_VRAM_CV.rel SGlib_bitmap_CV.rel SGlib_putPixel_CV.rel SGlib_setPixel_CV.rel SGlib_debug.rel
```

--------------------------------

### SG_initBitmapMode

Source: https://github.com/sverx/devkitsms/blob/master/SGlib/README.md

Initializes bitmap mode with specified foreground and background colors.

```APIDOC
## SG_initBitmapMode

### Description
Initializes bitmap mode with specified foreground and background colors.

### Method
Function

### Signature
`void SG_initBitmapMode (unsigned char foreground_color, unsigned char background_color)`

### Parameters
- `foreground_color` (unsigned char) - Required - Foreground color for bitmap mode.
- `background_color` (unsigned char) - Required - Background color for bitmap mode.

```

--------------------------------

### SG_getKeysReleased

Source: https://github.com/sverx/devkitsms/blob/master/SGlib/README.md

Gets the keys that were down last frame and up now.

```APIDOC
## SG_getKeysReleased

### Description
Gets the keys that were down last frame and up now.

### Method
Function

### Signature
unsigned int SG_getKeysReleased(void)

### Parameters
None

### Returns
unsigned int - The keys that were down last frame and up now.
```

--------------------------------

### Link and build PSGlib program with SDCC

Source: https://github.com/sverx/devkitsms/blob/master/README.md

Link and build an SMS/GG/SG/SC program using PSGlib for PSG audio/SFX. Add PSGlib.lib after the proper library. The output ROM size is a multiple of 16 KiB.

```bash
  sdcc -o your_program.ihx -mz80 --no-std-crt0 --data-loc 0xC000 crt0_sms.rel your_program.rel SMSlib.lib PSGlib.lib

```

```bash
  makesms your_program.ihx your_program.sms

```

--------------------------------

### SG_getKeysPressed

Source: https://github.com/sverx/devkitsms/blob/master/SGlib/README.md

Gets the keys that were up last frame and down now.

```APIDOC
## SG_getKeysPressed

### Description
Gets the keys that were up last frame and down now.

### Method
Function

### Signature
unsigned int SG_getKeysPressed(void)

### Parameters
None

### Returns
unsigned int - The keys that were up last frame and down now.
```

--------------------------------

### Link SGlib program for BASIC cartridge and convert to binary

Source: https://github.com/sverx/devkitsms/blob/master/README.md

Link an SGlib program for loading onto a BASIC IIIa/IIIb cartridge on the SC-3000. Use crt0_BASIC.rel and --code-loc 0x98a0 to place code after the interrupt handler. Convert the hex output to binary, then convert to an SC-3000 audio file with a tool like SC-TapeWave. Program size is limited: BASIC IIIa has 12 KiB of RAM following the load address, BASIC IIIb has 26 KiB.

```bash
  sdcc -o your_program.ihx -mz80 --no-std-crt0 --code-loc 0x98a0 --data-loc 0xC000 crt0_BASIC.rel your_program.rel SGlib.lib

```

```bash
  objcopy -Iihex -Obinary your_program.ihx your_program.bin

```

--------------------------------

### SG_getKeysStatus

Source: https://github.com/sverx/devkitsms/blob/master/SGlib/README.md

Gets the current status of the keys.

```APIDOC
## SG_getKeysStatus

### Description
Gets the current status of the keys.

### Method
Function

### Signature
unsigned int SG_getKeysStatus(void)

### Parameters
None

### Returns
unsigned int - The current status of the keys.
```

--------------------------------

### Turn on the screen with SMS_displayOn

Source: https://github.com/sverx/devkitsms/wiki/Home

Turns on the screen after loading tiles and palettes.

```c
SMS_displayOn()
```

--------------------------------

### SG_getTile

Source: https://github.com/sverx/devkitsms/blob/master/SGlib/README.md

Gets the tile at the current position.

```APIDOC
## SG_getTile

### Description
Gets the tile at the current position.

### Method
Function

### Signature
unsigned char SG_getTile(void)

### Parameters
None

### Returns
The tile value at the current position.
```

--------------------------------

### SG_getKeysHeld

Source: https://github.com/sverx/devkitsms/blob/master/SGlib/README.md

Gets the keys that were down last frame and still down now.

```APIDOC
## SG_getKeysHeld

### Description
Gets the keys that were down last frame and still down now.

### Method
Function

### Signature
unsigned int SG_getKeysHeld(void)

### Parameters
None

### Returns
unsigned int - The keys that were down last frame and still down now.
```

--------------------------------

### SG_getTileatXY

Source: https://github.com/sverx/devkitsms/blob/master/SGlib/README.md

Macro that gets the tile at the specified coordinates.

```APIDOC
## SG_getTileatXY

### Description
Macro that gets the tile at the specified coordinates.

### Method
Macro

### Signature
SG_getTileatXY(x,y)

### Parameters
- **x** - Required - X coordinate.
- **y** - Required - Y coordinate.

### Returns
The tile value at the specified coordinates.
```

--------------------------------

### ihx2sms -pp option

Source: https://github.com/sverx/devkitsms/blob/master/tools/legacy/ihx2sms/README.md

Pads the output ROM file to a size that is an exact power of 2. Possible output sizes are 16KB, 32KB, 64KB, 128KB, 256KB, and so on.

```bash
-pp        
```

--------------------------------

### Build Game Gear program with SMSlib

Source: https://github.com/sverx/devkitsms/blob/master/README.md

Compile, link, and build a Game Gear ROM using SMSlib with the TARGET_GG define. Link with crt0_sms.rel first and SMSlib_GG.lib after your code. The output ROM size is a multiple of 16 KiB and the checksum is calculated if the SEGA header is included.

```bash
  sdcc -c -mz80 --peep-file peep-rules.txt -D TARGET_GG your_program.c
```

```bash
  sdcc -o your_program.ihx -mz80 --no-std-crt0 --data-loc 0xC000 crt0_sms.rel your_program.rel SMSlib_GG.lib
```

```bash
  makesms your_program.ihx your_program.gg
```

--------------------------------

### Link objects and library into .ihx (sdcc)

Source: https://github.com/sverx/devkitsms/blob/master/examples/hello_sms/README.md

Links crt0_sms.rel, SMSlib.lib, and main.rel with sdcc to produce hello.ihx. crt0_sms.rel should come first, then libraries, then individual .rel files.

```shell
sdcc -o hello.ihx --no-std-crt0 --data-loc 0xC000 ../../crt0/crt0_sms.rel ../../SMSlib/src/SMSlib.lib    main.rel
```

--------------------------------

### SG_getKeyboardJoypadHeld

Source: https://github.com/sverx/devkitsms/blob/master/SGlib/README.md

Gets the keys held on the keyboard virtual joypad.

```APIDOC
## SG_getKeyboardJoypadHeld

### Description
Gets the keys held on the keyboard virtual joypad.

### Method
Function

### Signature
unsigned int SG_getKeyboardJoypadHeld(void)

### Parameters
None

### Returns
unsigned int - The keys held on the keyboard virtual joypad.
```

--------------------------------

### SG_getKeyboardJoypadPressed

Source: https://github.com/sverx/devkitsms/blob/master/SGlib/README.md

Gets the keys pressed on the keyboard virtual joypad.

```APIDOC
## SG_getKeyboardJoypadPressed

### Description
Gets the keys pressed on the keyboard virtual joypad.

### Method
Function

### Signature
unsigned int SG_getKeyboardJoypadPressed(void)

### Parameters
None

### Returns
unsigned int - The keys pressed on the keyboard virtual joypad.
```

--------------------------------

### SG_initSprites

Source: https://github.com/sverx/devkitsms/blob/master/SGlib/README.md

Initializes sprite handling.

```APIDOC
## SG_initSprites

### Description
Initializes sprite handling.

### Method
Function

### Signature
void SG_initSprites(void)

### Parameters
None

### Returns
None
```

--------------------------------

### assets2banks command line syntax

Source: https://github.com/sverx/devkitsms/blob/master/tools/assets2banks/README.md

Shows the full command-line syntax for assets2banks, including all available options. The default bank size is 16 KiB, and the --allowsplitting option enables splitting assets larger than a single bank.

```bash
assets2banks <asset folder> [--firstbank=<number>[,<size>]][--compile][--singleheader[=<filename>]][--exclude=<filename>][--allowsplitting][--banksize=<size>]
```

--------------------------------

### ihx2sms -pm option

Source: https://github.com/sverx/devkitsms/blob/master/tools/legacy/ihx2sms/README.md

Pads the output ROM file to a size that is a multiple of 64KB. Possible output sizes are 64KB, 128KB, 192KB, 256KB, 320KB, and so on.

```bash
-pm        
```

--------------------------------

### Compile and link SGlib program with SDCC

Source: https://github.com/sverx/devkitsms/blob/master/README.md

Compile, link, and build an SG-1000/SC-3000 program using SGlib. Link with crt0_sg.rel first and SGlib.lib after your code. The output ROM size is a multiple of 16 KiB.

```bash
  sdcc -c -mz80 your_program.c

```

```bash
  sdcc -o your_program.ihx -mz80 --no-std-crt0 --data-loc 0xC000 crt0_sg.rel your_program.rel SGlib.lib

```

```bash
  makesms your_program.ihx your_program.sg

```

--------------------------------

### Build ColecoVision ROM with SGlib

Source: https://github.com/sverx/devkitsms/blob/master/README.md

Compile, link, and convert a ColecoVision program using devkitSMS/SGlib. Include SGlib.h, compile with TARGET_CV, link with crt0_cv.rel first and SGlib_CV.lib after your code, then use sdobjcopy to produce the .col ROM. Optionally use --pad-to 0xC000 for 16 KiB or --pad-to 0xA000 for 8 KiB.

```bash
sdcc -c -mz80 -D TARGET_CV your_program.c
```

```bash
sdcc -o your_program.ihx -mz80 --no-std-crt0 --code-loc 0x8080 --data-loc 0x6000 crt0_cv.rel your_program.rel SGlib_CV.lib
```

```bash
sdobjcopy --input-target=ihex --output-target=binary --pad-to 0x10000 your_program.ihx your_program.col
```

--------------------------------

### Build ColecoVision ROM with PSGlib audio

Source: https://github.com/sverx/devkitsms/blob/master/README.md

Link and convert a ColecoVision program that uses PSGlib for audio/SFX. Include PSGlib.h, compile as before, and link with crt0_cv.rel, SGlib_CV.lib, and PSGlib_CV.lib. The sdobjcopy step is identical to the SGlib-only build.

```bash
sdcc -o your_program.ihx -mz80 --no-std-crt0 --code-loc 0x8080 --data-loc 0x6000 crt0_cv.rel your_program.rel SGlib_CV.lib PSGlib_CV.lib
```

```bash
sdobjcopy --input-target=ihex --output-target=binary --pad-to 0x10000 your_program.ihx your_program.col
```

--------------------------------

### Example usage of :discard

Source: https://github.com/sverx/devkitsms/blob/master/tools/assets2banks/README.md

Discards the first 16 elements from the array imported from mapdata.csv.

```plaintext
mapdata.csv
:text
:discard 0 16
```

--------------------------------

### assets2banks --firstbank=1,32768 --compile

Source: https://github.com/sverx/devkitsms/blob/master/tools/assets2banks/README.md

Invokes assets2banks to use the entire lower 32 KB for bank1, allowing allocation of assets larger than 16 KB or keeping all assets together for a 32 KiB ROM.

```bash
assets2banks assets --firstbank=1,32768  --compile
```

--------------------------------

### Basic VDP Handling Functions/Macros

Source: https://github.com/sverx/devkitsms/blob/master/SMSlib/README.md

Core VDP functions and macros for initialization, feature control, display, waiting for vBlank, scrolling, backdrop color, sprite mode, and tile selection.

```c
void SMS_init (void)                               /* you don't need to call this if you're using devkitSMS crt0 */
void SMS_VDPturnOnFeature (unsigned int feature)   /* check feature list in SMSlib.h */
void SMS_VDPturnOffFeature (unsigned int feature)
SMS_displayOn()                                    /* macro - turns on screen */
SMS_displayOff()                                   /* macro - turns off screen */
void SMS_waitForVBlank (void)                      /* wait until next vBlank starts */
void SMS_setBGScrollX (unsigned char scrollX)      /* scroll the background horizontally */
void SMS_setBGScrollY (unsigned char scrollY)      /* scroll the background vertically */
void SMS_setBackdropColor (unsigned char entry)    /* set which sprite palette entry will be used for backdrop */
void SMS_setSpriteMode (unsigned char mode)        /* check modes list in SMSlib.h */
void SMS_useFirstHalfTilesforSprites (_Bool usefirsthalf)  /* use tiles 0-255 for sprites if true, 256-511 if false */
```

--------------------------------

### SMS_loadTileMap

Source: https://github.com/sverx/devkitsms/wiki/Home

Loads a tilemap into the tilemap area. This function copies a tilemap from a source pointer to the tilemap starting at the specified coordinates.

```APIDOC
## SMS_loadTileMap

### Description
Loads a tilemap into the tilemap area.

### Function Signature
`SMS_loadTileMap (unsigned char x, unsigned char y, void *src, unsigned int len)`

### Parameters
- **x** (unsigned char) - Required - X coordinate (column) in tilemap.
- **y** (unsigned char) - Required - Y coordinate (row) in tilemap.
- **src** (void *) - Required - Pointer to the tilemap data source.
- **len** (unsigned int) - Required - Number of tile entries to load.

### Usage Example
```c
SMS_loadTileMap(0, 0, tilemap, 32*24);
```
```

--------------------------------

### SG_init

Source: https://github.com/sverx/devkitsms/blob/master/SGlib/README.md

Initializes the VDP. This function is called automatically if using devkitSMS crt0_sg.

```APIDOC
## SG_init

### Description
Initializes the VDP. This function is called automatically if using devkitSMS crt0_sg.

### Method
Function

### Signature
void SG_init(void)

### Parameters
None

### Returns
None
```

--------------------------------

### Set next sprite color index with SMS_setNextSpriteColoratIndex

Source: https://github.com/sverx/devkitsms/wiki/Advanced

Macro to set the starting index for updating sprite palette colors.

```c
SMS_setNextSpriteColoratIndex(i);
```

--------------------------------

### Build Master System program with SMSlib

Source: https://github.com/sverx/devkitsms/blob/master/README.md

Compile, link, and build a Master System ROM using SMSlib. Requires SDCC 4.2.0+ and the devkitSMS tools. Link with crt0_sms.rel first and SMSlib.lib after your code. The output ROM size is a multiple of 16 KiB and the checksum is calculated if the SEGA header is included.

```bash
  sdcc -c -mz80 --peep-file peep-rules.txt your_program.c
```

```bash
  sdcc -o your_program.ihx -mz80 --no-std-crt0 --data-loc 0xC000 crt0_sms.rel your_program.rel SMSlib.lib
```

```bash
  makesms your_program.ihx your_program.sms
```

--------------------------------

### Optional flags: -pm, -pp, -emptyfill, -mbin, -mbank

Source: https://github.com/sverx/devkitsms/blob/master/tools/makesms/README.md

Independent command-line flags controlling padding and merging. -pm pads to a multiple of 64 KiB, -pp pads to an exact power of 2, -emptyfill sets the fill byte value, -mbin and -mbank merge binary content into the ROM before updating header/checksum.

```bash
-pm        
```

```bash
-pp        
```

```bash
-emptyfill value
```

```bash
-mbin file:src:len:dst
```

```bash
-mbank file:src:banks:dst
```

--------------------------------

### Copy sprites to SAT with SMS_copySpritestoSAT

Source: https://github.com/sverx/devkitsms/wiki/Home

Copies the temporary sprite list to the SAT. Call this in the while loop, likely right after vBlank starts.

```c
SMS_copySpritestoSAT (void)
```

--------------------------------

### SMS_copySpritestoSAT

Source: https://github.com/sverx/devkitsms/wiki/Home

Copies the temporary sprite list to the SAT (Sprite Attribute Table). This should be called after adding sprites, typically right after vBlank starts.

```APIDOC
## SMS_copySpritestoSAT

### Description
Copies the temporary sprite list to the SAT.

### Function Signature
`SMS_copySpritestoSAT (void)`

### Usage Example
```c
SMS_copySpritestoSAT();
```
```

--------------------------------

### Main loop with SMS_waitForVBlank

Source: https://github.com/sverx/devkitsms/wiki/Home

Typical main loop that syncs game logic with the screen refresh. The loop runs forever, performs game logic, waits for vBlank, then updates the screen.

```c
while (true) {
  // do your game logic here...
  SMS_waitForVBlank();
  // ... then change the contents of the screen here
}
```

--------------------------------

### SMS_loadTiles

Source: https://github.com/sverx/devkitsms/wiki/Home

Loads tile data into VRAM. This function copies tile data from a source pointer to the VRAM starting at a specified tile index.

```APIDOC
## SMS_loadTiles

### Description
Loads tiles into VRAM.

### Function Signature
`SMS_loadTiles (void *src, unsigned int Tilefrom, unsigned int len)`

### Parameters
- **src** (void *) - Required - Pointer to the tile data source.
- **Tilefrom** (unsigned int) - Required - Starting tile index in VRAM.
- **len** (unsigned int) - Required - Number of tiles to load.

### Usage Example
```c
SMS_loadTiles(tiles, 0, 256);
```
```

--------------------------------

### Load tiles into VRAM with SMS_loadTiles

Source: https://github.com/sverx/devkitsms/wiki/Home

Loads a tilemap into VRAM starting at a specified tile index. Use this to load raw tile data.

```c
SMS_loadTiles (void *src, unsigned int Tilefrom, unsigned int len)
```

--------------------------------

### SG_displayOn

Source: https://github.com/sverx/devkitsms/blob/master/SGlib/README.md

Macro that turns on the screen.

```APIDOC
## SG_displayOn

### Description
Macro that turns on the screen.

### Method
Macro

### Signature
SG_displayOn()

### Parameters
None

### Returns
None
```

--------------------------------

### SMS_loadTileMapArea

Source: https://github.com/sverx/devkitsms/wiki/Home

Loads a rectangular area of a tilemap into the tilemap area. This function copies a rectangular region from a source pointer to the tilemap starting at the specified coordinates.

```APIDOC
## SMS_loadTileMapArea

### Description
Loads a rectangular area of a tilemap into the tilemap area.

### Function Signature
`SMS_loadTileMapArea (unsigned char x, unsigned char y, void *src, unsigned char width, unsigned char height)`

### Parameters
- **x** (unsigned char) - Required - X coordinate (column) in tilemap.
- **y** (unsigned char) - Required - Y coordinate (row) in tilemap.
- **src** (void *) - Required - Pointer to the tilemap data source.
- **width** (unsigned char) - Required - Width of the area in tiles.
- **height** (unsigned char) - Required - Height of the area in tiles.

### Usage Example
```c
SMS_loadTileMapArea(0, 0, tilemap, 32, 24);
```
```

--------------------------------

### Create SGlib.lib archive

Source: https://github.com/sverx/devkitsms/blob/master/SGlib/how to build this.txt

Create the SGlib.lib archive from the compiled .rel files using sdar. This is the standard library archive for the Sega Master System.

```bash
sdar r SGlib.lib SGlib.rel SGlib_spriteClip.rel SGlib_zx7.rel SGlib_zx7_VRAM.rel SGlib_bitmap.rel SGlib_putPixel.rel SGlib_setPixel.rel SGlib_debug.rel SGlib_keyboard.rel
```

--------------------------------

### Build crt0 for SG-1000 with sdasz80

Source: https://github.com/sverx/devkitsms/blob/master/crt0/README.md

Assembles the crt0 startup code for the SG-1000 using the sdasz80 assembler with the -g option to generate debug information.

```bash
sdasz80 -g -o crt0_sg.s
```

--------------------------------

### Using :discard attribute

Source: https://github.com/sverx/devkitsms/blob/master/tools/assets2banks/README.md

Discards _count_ array elements starting from _index_. If _count_ is omitted, only the _index_ element is discarded. A _count_ of 0 discards all elements from _index_ to the end.

```plaintext
:discard <index> [<count>]
```

--------------------------------

### Load background and sprite palettes

Source: https://github.com/sverx/devkitsms/wiki/Home

Loads palettes for the background and sprites. Call these before turning on the screen.

```c
SMS_loadBGPalette (void *palette)
SMS_loadSpritePalette (void *palette)
```

--------------------------------

### Link .rel files into first.ihx with sdcc

Source: https://github.com/sverx/devkitsms/blob/master/examples/first_test/README.md

Links the .rel files together. crt0_sms.rel should come first, then libraries, then individual .rel files. Produces first.ihx.

```bash
sdcc -o first.ihx --no-std-crt0 --data-loc 0xC000 ../../crt0/crt0_sms.rel ../../SMSlib/src/SMSlib.lib    main.rel
```

--------------------------------

### Functions for Reading Back Tilemap and VRAM

Source: https://github.com/sverx/devkitsms/blob/master/SMSlib/README.md

Reads tilemap entries and VRAM data, including macros to get tile at coordinates and functions to save tilemap areas or read VRAM directly.

```c
SMS_readNextTilefromXY(x,y)
unsigned short SMS_getTile(void)
SMS_getTileatXY(x,y)                   /* macro - returns the tile at X,Y (unsigned int) */

void SMS_saveTileMapArea(unsigned char x, unsigned char y, void *dst, unsigned char width, unsigned char height)
void SMS_readVRAM(void *dst, unsigned int src, unsigned int size)
```

--------------------------------

### void PSGFrame(void)

Source: https://github.com/sverx/devkitsms/blob/master/PSGlib/README.md

Should be called at a constant pace to advance the music playback.

```APIDOC
## void PSGFrame(void)

### Description
Should be called at a constant pace to advance the music playback.

### Parameters
None.

### Returns
None.
```

--------------------------------

### SDCC linker for 32 KiB ROM with BANK1 at 0x0000

Source: https://github.com/sverx/devkitsms/blob/master/tools/assets2banks/README.md

Linker command for a 32 KiB ROM when using assets2banks' --compile option with --firstbank=1,32768. Only bank1.rel is needed.

```bash
sdcc -o output.ihx -mz80 --data-loc 0xC000 -Wl-b_BANK1=0x0000 --no-std-crt0 crt0_sms.rel main.rel SMSlib.lib bank1.rel
```

--------------------------------

### Load PSGaiden compressed tiles with SMS_loadPSGaidencompressedTiles

Source: https://github.com/sverx/devkitsms/wiki/Home

Loads tiles compressed with PSGaiden into VRAM. Use this for compressed tile data.

```c
SMS_loadPSGaidencompressedTiles (void *src, unsigned int tilefrom)
```

--------------------------------

### Modify multiple elements

Source: https://github.com/sverx/devkitsms/blob/master/tools/assets2banks/README.md

Modifies length array elements from start using the listed action and values, repeating them if needed. Valid actions are 'add', 'and', 'or' and 'xor'. Accepts decimal or 0x-prefixed hex values.

```plaintext
:modify <action> <start> <length> <value> [<value>[...]]
```

--------------------------------

### assets2banks --firstbank=1,8192 --compile

Source: https://github.com/sverx/devkitsms/blob/master/tools/assets2banks/README.md

Invokes assets2banks to use the first 8192 bytes of the lower 32 KB for bank1, allowing assets to be allocated there. This may help save a whole bank. Also creates bank1.c and possibly bank1.h files.

```bash
assets2banks assets --firstbank=1,8192 --compile
```

--------------------------------

### Build ColecoVision MegaCart ROM with bank paging

Source: https://github.com/sverx/devkitsms/blob/master/README.md

Build a ColecoVision MegaCart ROM with bank paging. Compile each 16 KiB data bank with a distinct CONST segment (e.g., BANK1, BANK2), compile the program with TARGET_CV, link with -Wl-b_BANK#=0x#C000 and bank .rel files last, then run makecvmc. Only 16,320 bytes are available per bank, and the final ROM is 128, 256, 512, or 1024 KiB.

```bash
sdcc -c -mz80 --constseg BANK1 bank1.c
sdcc -c -mz80 --constseg BANK2 bank2.c
```

```bash
sdcc -c -mz80 -D TARGET_CV your_program.c
```

```bash
sdcc -o your_program.ihx -mz80 --no-std-crt0 --code-loc 0x8080 --data-loc 0x6000 -Wl-b_BANK1=0x1C000 -Wl-b_BANK2=0x2C000 crt0_cv.rel your_program.rel SGlib_CV.lib bank1.rel bank2.rel
```

```bash
makecvmc your_program.ihx your_program.rom
```

--------------------------------

### SG_loadZX7compressedBGTiles

Source: https://github.com/sverx/devkitsms/blob/master/SGlib/README.md

Macro to decompress tiles to background tiles.

```APIDOC
## SG_loadZX7compressedBGTiles

### Description
Macro to decompress tiles to background tiles.

### Method
Macro

### Signature
SG_loadZX7compressedBGTiles(src,tilefrom)

### Parameters
- **src** - Required - Source compressed data.
- **tilefrom** - Required - Starting tile index.

### Returns
None
```

--------------------------------

### Using :text attribute for text asset

Source: https://github.com/sverx/devkitsms/blob/master/tools/assets2banks/README.md

Declares that the asset file is a text file containing data to be parsed. Values can be decimal or 0x-prefixed hex, negative down to -128 for char arrays and -32768 for int arrays. Separators can be spaces, tabs, newlines, commas, semicolons, or brackets; comments start with #.

```plaintext
sin_x_LUT.txt
:text
```

--------------------------------

### MBMlib sound effect functions (MBMSFXPlay, MBMSFXPlayLoop, MBMSFXCancelLoop, MBMSFXStop, MBMSFXGetStatus, MBMSFXFrame)

Source: https://github.com/sverx/devkitsms/blob/master/MBMlib/README.md

Functions for sound effect replay. MBMSFXPlay fires a sound effect; MBMSFXPlayLoop starts auto-retrigger mode; MBMSFXCancelLoop cancels auto-retriggering; MBMSFXStop stops immediately; MBMSFXGetStatus returns MBMSFX_STOPPED (0) or MBMSFX_PLAYING; MBMSFXFrame must be called once per frame.

```c
void MBMSFXPlay (void *sound_effect)     /* this will fire your sound effect */
void MBMSFXPlayLoop (void *sound_effect) /* this will start your sound effect in auto-retrigger mode */
void MBMSFXCancelLoop (void)             /* tells the library to cancel the auto-retrigging on the currently playing sound effect */

void MBMSFXStop (void)                   /* this stops the playing sound effect immediately */

unsigned char MBMSFXGetStatus (void)     /* get the current status of the sound effect. possible values are: */

MBMSFX_STOPPED                           /* (zero) no sound effect currently playing */
MBMSFX_PLAYING                           /* a sound effect is playing */

void MBMSFXFrame (void)                  /* you should call this once per frame to replay the sound effect */
```

--------------------------------

### MBMlib module replay functions (MBMPlay, MBMCancelLoop, MBMPlayNoRepeat, MBMStop, MBMResume, MBMGetStatus, MBMFadeOut, MBMFrame)

Source: https://github.com/sverx/devkitsms/blob/master/MBMlib/README.md

Functions for replaying MoonBlaster modules on SEGA Master System / Mark III with FM chip. MBMPlay starts the module and loops if defined; MBMCancelLoop stops looping at next loop point; MBMPlayNoRepeat plays once; MBMStop pauses; MBMResume resumes; MBMGetStatus returns MBM_STOPPED (0) or MBM_PLAYING; MBMFadeOut fades out with fade_fraction as denominator (0 invalid, 1 immediate, 255 slowest); MBMFrame must be called once per frame.

```c
void MBMPlay (void *module)              /* this will make your MoonBlaster module start and, if a loop has been defined in the module, loop infinitely */
void MBMCancelLoop (void)                /* tell the library to stop the looping tune at next loop point */
void MBMPlayNoRepeat (void *module)      /* this will make your MoonBlaster module start and stop at the end even if the module defined a loop */

void MBMStop (void)                      /* this will make the module stop (pause) */
void MBMResume (void)                    /* this will make your stopped (paused) tune resume playing */

unsigned char MBMGetStatus (void)        /* get the current status of the tune. possible values are: */

MBM_STOPPED                              /* (zero) no module currently playing */
MBM_PLAYING                              /* a module is playing */

void MBMFadeOut (unsigned char fade_fraction)   /* fade out the tune until the volume is zero and stop the tune */
                                                /* parameter is a fraction denominator so: */
                                                /* 0 is not valid, 1 will make the fade immediate and 255 is the slowest fade possible */

void MBMFrame (void)                     /* you should call this once per frame to replay the tune */
```

--------------------------------

### Initialize sprites with SMS_initSprites

Source: https://github.com/sverx/devkitsms/wiki/Home

Declares that you will list all sprites for the next frame. Call this each frame before adding sprites.

```c
SMS_initSprites (void)
```

--------------------------------

### Build crt0 for ColecoVision with sdasz80

Source: https://github.com/sverx/devkitsms/blob/master/crt0/README.md

Assembles the crt0 startup code for the ColecoVision using the sdasz80 assembler with the -g option to generate debug information.

```bash
sdasz80 -g -o crt0_cv.s
```
Tokens:
Raw