NeoGeo Development Wiki - User contributions [en]

HOW TO PLAY

2021-03-03T04:39:31Z

WLivi: /* Tilemap */ minor clarification

[[File:howtoplay_nam.png|thumb|A "scripted" how-to-play screen.]]

The HOW_TO_PLAY ($C00474) [[system ROM]] call builds and animates an "how to play" screen from a command list. Only a few games use this call.

The graphics are set up using the [[fix layer]] with hardcoded tile numbers.

=Command list=

The command list must be loaded at $10F300 (how many bytes reserved ?).

Each command is a longword (4 bytes):

* The rightmost byte is the command parameter
* The next byte is the command type (0~3)
* If the command type isn't recognized, the longword is processed as being a pointer to a [[MESS OUT]] data buffer
* The end command is $00000000

<pre>
00000000 00000000 000000TT PPPPPPPP
</pre>

==Type 0: Loop control==

* If the parameter byte is less than $FF: Set a loop counter to that value
* If the parameter byte is equal to $FF: Decrement the loop counter and loop back to the previous setup command until it reaches 0

==Type 1: Joystick state==

Sets the color of each joystick direction arrow.

* 1 is light blue (pressed)
* 0 is dark blue (released)

{{8BitRegister
|Up-Right
|1
|Right
|1
|Down-Right
|1
|Down
|1
|Down-Left
|1
|Left
|1
|Up-Left
|1
|Up
|1
}}

If followed by a null command ($0.l) the next 16-bit word specifies a number of frames to wait before executing the next command.

==Type 2: Buttons state==

Sets the state of each button.

* 1 is pressed
* 0 is released

{{8BitRegister
| -
|4
|D
|1
|C
|1
|B
|1
|A
|1
}}

If followed by a null command ($0.l) the next 16-bit word specifies a number of frames to wait before executing the next command.

==Any other type: Text update==

The longword value is a pointer to a [[MESS_OUT]] data buffer.

This command is '''always''' followed by a 16-bit word value which specifies a number of frames to wait before executing the next command.

=Example=

[[NAM-1975]] sets up the following command list:

<pre>
0000 0200 All buttons released
0000 01FF All arrows highlighted
0010 F3E2 MESS_OUT write "NAM 1975" "CONTROL HERO AND CURSOR"
0004 Wait 4 frames
0000 000C Init loop counter to 12
0000 0100 All arrows cleared <--------------,
0000 0000 Wait... |
0008 ...8 frames |
0000 01FF All arrows highlighted |
0000 0000 Wait... |
0008 ...8 frames |
0000 00FF Loop back (blink all arrows 12 times) --'
0000 0201 A button is pressed
0000 0100 All arrows cleared
0010 F418 MESS_OUT write "MACHINE GUN"
0004 Wait 4 frames
0000 000C Init loop counter to 12
0000 0200 All buttons released <--------------,
0000 0000 Wait... |
0008 ...8 frames |
0000 0201 A button is pressed |
0000 0000 Wait... |
0008 ...8 frames |
0000 00FF Loop back (blink A button 12 times) ----'
...
</pre>

=List of games known to use HOW_TO_PLAY=

* [[NAM-1975]]
* [[Baseball Stars Professional]]
* [[Mahjong Kyo Retsuden]]
* ...

=Tilemap=
[[File:howtoplay_tilemap.png|thumb|how-to-play tilemap, with each 8x16 block turned into the low-byte of it's hex address]]
The tiles that make up the HOW_TO_PLAY screen are found in pages 7 and 8 of the Fix rom. Much like how MESS OUT handles 8x16 text, each tile in page 7 has a counterpart at the same position on page 8, which gets displayed immediately below. (The exception to this is the black tiles around the edges, which are all 0x07FF.) 
Given this unifom layout of adjacent rows, the below table combines each pair and lists only the low byte.

The interior of the lower text area is initialized with rows of 0x9920 and 0x9A20; the 8x16 spaces from fontset 9, in palette 9.
{|class="wikitable"
|+Overall Layout
|-
|FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF
|-
|FF||00||01||04||05||05||05||05||05||05||05||05||05||05||05||05||05||05||05||06||07||07||07||07||07||07||07||07||07||07||07||07||07||07||07||07||07||07
|-
|FF||02||03||08||09||09||09||09||09||09||09||09||09||09||09||09||09||09||09||0A||0B||0B||0B||0B||0B||0B||0B||0B||0B||0B||0B||0B||0B||0B||0B||0B||0B||0B
|-
|FF||03||03||0C||0D||0E||0F||10||11||12||13||14||15||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||63||64||65
|-
|FF||03||03||0C||5C||5D||5D||16||17||18||19||1A||1B||5D||5D||5D||5D||5D||5D||5D||5D||2C||2D||2E||2F||30||31||32||33||34||35||36||37||5D||5D||5D||5D||5D
|-
|FF||03||03||0C||5D||5D||5D||1C||1D||1E||1F||20||21||5D||5D||5D||5D||5D||38||39||3A||3B||3C||3D||3E||3F||40||41||42||43||44||45||46||5D||5D||5D||5D||5D
|-
|FF||03||03||0C||5E||5D||5D||22||23||24||25||26||27||5D||5D||5D||5D||5D||47||48||49||4A||4B||4C||4D||4E||4F||50||51||52||53||54||55||5D||5D||5D||5D||5D
|-
|FF||03||03||0C||5F||5D||5D||5D||28||29||2A||2B||5D||5D||5D||5D||5D||5D||56||57||58||59||59||59||59||59||59||59||59||59||59||5A||5B||5D||5D||5D||5D||5D
|-
|FF||68||69||0C||60||61||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||66||67
|-
|FF||6A||6B||6C||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||76||77||77||77
|-
|FF||03||03||6F||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||78||79||79||79
|-
|FF||6E||03||70||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||7A||7B||7B||7B
|-
|FF||72||73||71||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||7C||7D||7D||7D
|-
|FF||FF||FF||74||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||7E||FF||FF||FF
|}

* The joystick (10-2B) uses palette 0x0, which changes to highlight the directions.
** Within palette 0x0, colors 5-C map to the joystick directions, starting at Up and rotating anticlockwise.
** Note: the top-halves of tiles 10-15 are in palette 0xD instead.
* The buttons (2C-5B) use palette 0xA when dim, and 0xB when illuminated.
** A tiles: 38-3B, 47-4B, 56-58
** B tiles: 2C-2F, 3C-3E, 4C-4D
** C tiles: 30-33, 3F-42, 4E-51
** D tiles: 34-37, 43-46, 52-55
** tiles 59-5B are drawn in the dim palette and never turn bright
* The text-boxes frames (04-06, 08-0A, 6C-6D, 6F-71, 74-76, 78, 7A, 7C, 7E) have palette 0xC.
* The rest of the control panel uses palette 0xD.

[[Category:Code]]
[[Category:BIOS calls]]

HOW TO PLAY

2021-03-03T04:20:07Z

WLivi: Tilemap data

[[File:howtoplay_nam.png|thumb|A "scripted" how-to-play screen.]]

The HOW_TO_PLAY ($C00474) [[system ROM]] call builds and animates an "how to play" screen from a command list. Only a few games use this call.

The graphics are set up using the [[fix layer]] with hardcoded tile numbers.

=Command list=

The command list must be loaded at $10F300 (how many bytes reserved ?).

Each command is a longword (4 bytes):

* The rightmost byte is the command parameter
* The next byte is the command type (0~3)
* If the command type isn't recognized, the longword is processed as being a pointer to a [[MESS OUT]] data buffer
* The end command is $00000000

<pre>
00000000 00000000 000000TT PPPPPPPP
</pre>

==Type 0: Loop control==

* If the parameter byte is less than $FF: Set a loop counter to that value
* If the parameter byte is equal to $FF: Decrement the loop counter and loop back to the previous setup command until it reaches 0

==Type 1: Joystick state==

Sets the color of each joystick direction arrow.

* 1 is light blue (pressed)
* 0 is dark blue (released)

{{8BitRegister
|Up-Right
|1
|Right
|1
|Down-Right
|1
|Down
|1
|Down-Left
|1
|Left
|1
|Up-Left
|1
|Up
|1
}}

If followed by a null command ($0.l) the next 16-bit word specifies a number of frames to wait before executing the next command.

==Type 2: Buttons state==

Sets the state of each button.

* 1 is pressed
* 0 is released

{{8BitRegister
| -
|4
|D
|1
|C
|1
|B
|1
|A
|1
}}

If followed by a null command ($0.l) the next 16-bit word specifies a number of frames to wait before executing the next command.

==Any other type: Text update==

The longword value is a pointer to a [[MESS_OUT]] data buffer.

This command is '''always''' followed by a 16-bit word value which specifies a number of frames to wait before executing the next command.

=Example=

[[NAM-1975]] sets up the following command list:

<pre>
0000 0200 All buttons released
0000 01FF All arrows highlighted
0010 F3E2 MESS_OUT write "NAM 1975" "CONTROL HERO AND CURSOR"
0004 Wait 4 frames
0000 000C Init loop counter to 12
0000 0100 All arrows cleared <--------------,
0000 0000 Wait... |
0008 ...8 frames |
0000 01FF All arrows highlighted |
0000 0000 Wait... |
0008 ...8 frames |
0000 00FF Loop back (blink all arrows 12 times) --'
0000 0201 A button is pressed
0000 0100 All arrows cleared
0010 F418 MESS_OUT write "MACHINE GUN"
0004 Wait 4 frames
0000 000C Init loop counter to 12
0000 0200 All buttons released <--------------,
0000 0000 Wait... |
0008 ...8 frames |
0000 0201 A button is pressed |
0000 0000 Wait... |
0008 ...8 frames |
0000 00FF Loop back (blink A button 12 times) ----'
...
</pre>

=List of games known to use HOW_TO_PLAY=

* [[NAM-1975]]
* [[Baseball Stars Professional]]
* [[Mahjong Kyo Retsuden]]
* ...

=Tilemap=
[[File:howtoplay_tilemap.png|thumb|how-to-play tilemap, with each 8x16 block turned into the low-byte of it's hex address]]
The tiles that make up the HOW_TO_PLAY screen are found in pages 7 and 8 of the Fix rom. Much like how MESS OUT handles 8x16 text, each tile in page 7 has a counterpart at the same position on page 8, which gets displayed immediately below. (The exception to this is the black tiles around the edges, which are all 0x07FF.) 
Given this unifom layout of adjacent rows, the below table combines each pair and lists only the low byte.

The interior of the lower text area is initialized with rows of 0x9920 and 0x9A20; the 8x16 spaces from fontset 9, in palette 9.
{|class="wikitable"
|+Overall Layout
|-
|FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF||FF
|-
|FF||00||01||04||05||05||05||05||05||05||05||05||05||05||05||05||05||05||05||06||07||07||07||07||07||07||07||07||07||07||07||07||07||07||07||07||07||07
|-
|FF||02||03||08||09||09||09||09||09||09||09||09||09||09||09||09||09||09||09||0A||0B||0B||0B||0B||0B||0B||0B||0B||0B||0B||0B||0B||0B||0B||0B||0B||0B||0B
|-
|FF||03||03||0C||0D||0E||0F||10||11||12||13||14||15||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||0F||63||64||65
|-
|FF||03||03||0C||5C||5D||5D||16||17||18||19||1A||1B||5D||5D||5D||5D||5D||5D||5D||5D||2C||2D||2E||2F||30||31||32||33||34||35||36||37||5D||5D||5D||5D||5D
|-
|FF||03||03||0C||5D||5D||5D||1C||1D||1E||1F||20||21||5D||5D||5D||5D||5D||38||39||3A||3B||3C||3D||3E||3F||40||41||42||43||44||45||46||5D||5D||5D||5D||5D
|-
|FF||03||03||0C||5E||5D||5D||22||23||24||25||26||27||5D||5D||5D||5D||5D||47||48||49||4A||4B||4C||4D||4E||4F||50||51||52||53||54||55||5D||5D||5D||5D||5D
|-
|FF||03||03||0C||5F||5D||5D||5D||28||29||2A||2B||5D||5D||5D||5D||5D||5D||56||57||58||59||59||59||59||59||59||59||59||59||59||5A||5B||5D||5D||5D||5D||5D
|-
|FF||68||69||0C||60||61||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||62||66||67
|-
|FF||6A||6B||6C||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||6D||76||77||77||77
|-
|FF||03||03||6F||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||78||79||79||79
|-
|FF||6E||03||70||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||7A||7B||7B||7B
|-
|FF||72||73||71||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||20||7C||7D||7D||7D
|-
|FF||FF||FF||74||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||75||7E||FF||FF||FF
|}

* The joystick (10-2B) uses palette 0x0, which changes to highlight the directions.
** Colors 0x5-0xC map to the joystick directions, starting at Up and rotating anticlockwise.
** Note: the top-halves of tiles 10-15 are in palette 0xD instead.
* The buttons (2C-5B) use palette 0xA when dim, and 0xB when illuminated.
** A tiles: 38-3B, 47-4B, 56-58
** B tiles: 2C-2F, 3C-3E, 4C-4D
** C tiles: 30-33, 3F-42, 4E-51
** D tiles: 34-37, 43-46, 52-55
* The text-boxes frames (04-06, 08-0A, 6C-6D, 6F-71, 74-76, 78, 7A, 7C, 7E) have palette 0xC.
* The rest of the control panel uses palette 0xD.

[[Category:Code]]
[[Category:BIOS calls]]

File:Howtoplay tilemap.png

2021-03-03T04:00:12Z

WLivi: the Howtoplay screen rendered with a hacked fix rom, to showcase the tilemap. A simple palette reference has been added to the lower text-box.

== Summary ==
the Howtoplay screen rendered with a hacked fix rom, to showcase the tilemap. A simple palette reference has been added to the lower text-box.

MESS OUT

2021-03-03T02:03:24Z

WLivi: /* Command 9: Write Japanese text */

=MESS_OUT ($C004CE): Generic VRAM output=
[[File:Mess_out.png|frame|right]]

MESS_OUT executes the command buffer in the [[System ROM]]'s work RAM that starts at '''BIOS_MESS_BUFFER''' (constant $10FF00) and goes up to '''BIOS_MESS_POINT''' (longword variable $10FDBE). This can be used to display text messages, boxes... on the [[fix layer]] (is it used for sprites too ?).

<s>MESS_OUT is automatically called in the [[SYSTEM_INT1]] call</s>. '''BIOS_MESS_BUSY''' ($10FDC2.b) can be used to prevent this (when setting up the command list, for example).

The command buffer can be made of commands directly, or pointers to lists in ROM or user RAM. To put commands directly into the buffer, a null pointer ($00.l) needs to be placed before the command list.

Commands are always words.

=Commands=
==Command 0: End of command list==
1 word: $0000

==Command 1: Set data format==
2 words:
{{16BitRegister|0|6|Byte/Word|1|End code/Data size|1|$01|8}}

This command specifies if the data will be in bytes or words, and if the size is defined or if an end code has to be reached.

;If data is in bytes (bit 9 = 0):
:The next word's upper byte will be the data's constant upper byte (since VRAM can only be written in words).
:If the data is limited by an end code (bit 8 = 0), the next word's lower byte will be the end code's value.
:If the data size is defined (bit 8 = 1), the next word's lower byte will be the size (so max length is $FF).

;If data is in words (bit 9 = 1):
:If the data is limited by an end code (bit 8 = 0), the next word will be the end code's value.
:If the data size is defined (bit 8 = 1), the next word will be the size (so max length is $FFFF).

Examples:
<syntaxhighlight>
dc.w $0001,$15FF ;Data will be read in bytes, upper byte will always be $15, end code is $FF.
dc.w $0101,$1520 ;Data will be read in bytes, upper byte will always be $15, data length is $20.
dc.w $0201,$8000 ;Data will be read in words, end code is $8000.
dc.w $0301,$2044 ;Data will be read in words, data length is $2044.
</syntaxhighlight>

The format stays the same until command 1 is used again.

==Command 2: Set auto-increment==
*1 word
{{16BitRegister|Auto-inc value|8|$02|8}}

Sets the auto-increment value (written to '''VRAM_MOD''' ($3C0004)). Is the value sign-extended or not ?
<syntaxhighlight>
dc.w $2002 ;Set auto-inc to $20
</syntaxhighlight>

==Command 3: Set VRAM address==
*2 words
Sets the VRAM address written to '''VRAM_ADDR''' ($3C0000)) to the next word's value.
<syntaxhighlight>
dc.w $0003,$7201 ;Set VRAM address to $7201
</syntaxhighlight>

==Command 4: Set data address==
*3 words
Sets the output data address to the next longword. Actual writes to VRAM are done with this command.
<syntaxhighlight>
dc.w $0004
dc.l MESSAGE
</syntaxhighlight>

==Command 5: Add to current VRAM address==
*2 words
Add the next word to the current VRAM address. (This is different from command 2). Useful to skip lines or spaces.
<syntaxhighlight>
dc.w $0005,$001F ;Add $1F to the current VRAM address
</syntaxhighlight>

==Command 6: Resume data output==
*1 word
Resume data output (instead of using command 4 again, keep going from the last address).

==Command 7: Directly define output data==
*at least 2 words
Directly define the data (instead of using command 4 to point to it). Don't forget the padding byte if the data ends on an odd address.
<syntaxhighlight>
dc.w $0007
dc.b $30,$31,$34,$45,$FF
dc.b $00 ;Pad byte
</syntaxhighlight>

==Command 8: Write text with 8x16 font==
*at least 2 words
{{16BitRegister|Upper data byte (fontset number)|8|$08|8}}

Writes with the 8*16 pixels fix font. The commands upper byte will be the data's constant upper byte. The next bytes are data, and the end code is $FF.

The auto-inc is automaticaly set to $20.

<syntaxhighlight>
dc.w $0108 ;Tileset 1
dc.b $44,$51 ;Data
dc.b $FF ;End code
dc.b $00 ;Pad byte
</syntaxhighlight>

==Command 9: Write Japanese text==
Same as command 8 but for Japanese characters.

Upper-case ASCII (0x20-0x5F) and characters 0x80-0xFE are handled identically to command 8. 
Characters 0x00-0x19 are hiragana with diacritic marks. 
Characters 0x60-0x7A are katakana with diacritic marks. 

The tiles used for this are all taken from page 0, irrespective of the selected fontset. 
0x00-0x1F map to 0x080-0x09F (upper) and 0x0C0-0x0DF (lower). 
0x60-0x7F map to 0x0A0-0x0BF (upper) and 0x0E0-0x0FF (lower). 

==Command A: Call sub list==
*3 words
Call sub command list. The next longword is a pointer to another command list. Return has to be made using command B.
<syntaxhighlight>
dc.w $000A
dc.l SUBLIST
</syntaxhighlight>
'''The call stack seems to be 5 addresses deep.''' Be sure to avoid nesting too many list calls.

==Command B: Return from sub list==
*1 word
Return to calling command list.

==Command C: Repeated data output==
*2 words
Repeat output. The upper byte of the command is the number of times to output the next word.

<syntaxhighlight>
dc.w $090C,$0147 ;Outputs $0147 9 times
</syntaxhighlight>

==Command D: Repeat and increment output==
*2 words

Repeat and increment output. The upper byte of the command is the number of times to output the next word. The lower byte of the data is incremented each time.
<syntaxhighlight>
dc.w $040D,$42FE ;Outputs $42FE,$42FF,$4200,$4201
</syntaxhighlight>

=Example code and command lists=
(Slightly modified code from SNK's doc, output gives the above screencap.)

<syntaxhighlight>
bset.b #0,BIOS_MESS_BUSY
movea.l BIOS_MESS_POINT,a0 ;Get current pointer in buffer
move.l #0,(a0)+ ;Direct commands
move.w #3,(a0)+ ;Set VRAM address to $7318
move.w #$7318,(a0)+
move.w #$0301,(a0)+ ;Words, size = 1
move.w #$0001,(a0)+
move.w #$0007,(a0)+ ;Output data
move.w $100000,(a0)+
move.w #0,(a0)+ ;End of this list
move.l #MESSAGE1,(a0)+ ;Pointer to list in ROM
move.l a0,BIOS_MESS_POINT ;Update pointer
bclr.b #0,BIOS_MESS_BUSY ;Ready to go
rts

MESSAGE1:
dc.w $0001 ;Bytes, upper = $00, end code = $FF
dc.w $00FF
dc.w $2002 ;Auto-inc = $20
dc.w $0003 ;VRAM address = $7024
dc.w $7024
dc.w $0004 ;Write "MESSAGE1"
dc.l MS1

dc.w $0005 ;Next line
dc.w $0001
dc.w $0006 ;Resume, write "MESSAGE2"
dc.w $0005 ;Next line
dc.w $0001

dc.w $0007 ;Direct data output
dc.b "MESSAGE3"
dc.w $FF00 ;End code and pad byte

dc.w $0005 ;Next line
dc.w $0001

dc.w $0108 ;8x16 write, fontset 1
dc.b "ABCDE",$FF
dc.w $0005 ;Next line
dc.w $0001
dc.w $0109 ;8x16 write, fontset 1
dc.b 0,1,2,3,4,$FF
dc.w $0005 ;Next 2 lines
dc.w $0002
dc.w $000A ;Sub list calls
dc.l SUB_MESS
dc.w $000A
dc.l SUB_MESS
dc.w $000A
dc.l SUB_MESS
dc.w $0000

MS1:
dc.b "MESSAGE 1",$FF
dc.b "MESSAGE 2",$FF

SUB_MESS:
dc.w $090C ;Outputs $0022 9 times
dc.w $0022
dc.w $070D ;Outputs $0042 7 times with inc
dc.w $0042
dc.w $0005 ;Next line
dc.w $0001
dc.w $000B ;Return
</syntaxhighlight>

[[Category:Code]]
[[Category:BIOS calls]]