MZX 2.65 public beta

This is the first public release of MZX 2.65. It is BETA. If you have a problem, please mail me at kutnick@andrews.edu. It has been through private beta, but it is expected that some minor problems still exist.

This text file will outline the new features and how to use them.

New features:
 Shows current mod playing in debug window
 Better partial char set management
 Subroutines
 Sprites
 Hex representation of counters
 Bug fixes
 Misc counters

Misc new counters: (ro = read only, wo = write only)
 fread_counter (ro), fwrite_counter (wo):
 reads/writes a full counter from file
 
 board_w (ro), board_h (ro)
 returns current board width/height

 robot_id_(name) (ro)
 returns the ID number of robot "name"

 r(number).(counter) (ro)
 returns the value of the local counter for the robot with the given ID
 Note that you cannot write to another robot's counter.

Better partial char set management:
 You can now save partial charsets in the editor by prefixing the name with #xx, where x is a hex
 number for how large to save it, ie:

 #04blah.chr saves blah.chr as a 4 large set.

 You can now load partial charsets into the middle of the current charset by prefixing the load name
 with +xx where xx is a hex amount signifying offset position in the charset, ie:

 +F0blah.chr loads blah.chr into position 240.

Sprites
 Sprites are a relatively complex new addition; they require a  bit of work to manage but are rather
 powerful.

 A sprite is a rectangular entity of squares that exists either between the board and the overlay or
 above the overlay. When you set a new position for the sprite, the sprite moves.

 You may have up to 64 sprites; sprite indexing starts at ZERO. So spr0 is the first sprite.

 To make a sprite you first draw the sprite on the board (not the overlay). Then you set where the sprite
 is by setting sprN_refx and sprN_refy for the position, and sprN_width and sprN_height for the size.

 You then initialize + put the sprite at an x/y position by using the "put" command as following:

 put cxx sprite pyy x y

 Will put sprite number yy at x y, with the color xx. Use c?? to have it use the colors it has on the
 board. Background 0 takes on the background of the color beneath it, and char 32 is not drawn at all.
 
 You may also set or check the counters directly, sprN_x and sprN_y to move the sprite or determine its
 location.

Collision detection
 Along with the sprites there are collision detection routines to manage whether or not the sprite
 collides with other sprites or the background. 

 First you must set up a bounding rectangle that defines where the sprite is "solid":

 sprN_cx, sprN_cy - the bounding box's coordinates WITHIN the sprite
 sprN_cwidth, sprN_cheight - the bounding box's size

 To check for collision do the following:

 if cxx sprite_colliding pxx x y "label"; it will call label if the
 sprite is colliding with anything in the background (it collides only with customblocks) or other sprites.

 If the color is c?? x and y will be RELATIVE to the sprite, otherwise they will be relative to the board.
 If you use c?? then a rel before the command won't do anything.

 Afterwards it will set up the following counters:

 spr_collisions - the number of collisions reported
 spr_clistN - the status of collision number N; it will be the sprites number or -1 if the background.

 You may also invoke a collision detection routine of a certain sprite by the following:

 set "sprN_clist" 1

 Be sure to only check the numbers that are within the "collisions" range, because 0 is a valid number
 (colliding with sprite #0)

 Use if c?? sprite pxx x y "label" to determine if the x/y given is within the sprite currently.

Sprite flags
 The following will set properties of individual sprites; all of the sprites have these properties; set
 to 0 to disable, 1 to enable.

 sprN_static - determines if the sprite is "static" in the same sense of static overlay, or if it scrolls
 with the board.
 sprN_overlaid - if set to 1, sprite is drawn OVER the overlay. Otherwise it is drawn underneath the overlay.
 sprN_ccheck - if set to 1 then collision detection will only flag if not only bounding boxes are overlapped,
  but individial CHARACTERS are. Thus, if a char is 32 at a position it's not solid there. This can give
  much more accurate collision detection.
 sprN_off - turns the sprite off if it has already been initialized

 All of these are write only - you cannot read the values back from them.

Sprite draw order
 By default, sprites are drawn in the order of their sprite numbers (ie, 0 is drawn first, 1 is drawn second, etc.)
 If you set "spr_yorder" then sprites will be drawn according to their y value, relative to the screen. This can be
 very useful for top-down games. Set it to 1 to enable it, 0 to disable it.

Misc.
 If you set the "spr_num" counter to a value, and use p?? as a sprite, it will use the value from spr_num.
 This is useful for making semi-variable params.

 If you set sprN_setview to anything it will do the equivilent of "resetview" for the sprite N.

 If you set sprN_swap to X it will swap sprite N with sprite X.

Limitations
 Right now the largest limitation to sprites is that you only have one set per game; every board does NOT have its own
 set of sprites. So if you want to save them between boards be sure to save the x/y information to counters somewhere
 (you probably already had them in counters to begin with)... hopefully unless something went horribly wrong after I wrote
 this sprite information WILL be saved to save files.


Subroutines:

 Subroutines are like labels but you can return from them, meaning you can resume from whereever you called them (or wherever
 the robot was when it was sent the label). To be able to do a subroutine, you must first initialize a stack in the first line
 of the robot as a comment. This is important! The line should be set up like this:

 . "#*-1-2-3-4-...-n"
 
 The #* part is just that, #*, you must enter those chars. The other ones signify how deep the stack is, or in other words,
 how many times you may call a new subroutine without returning from the one you're in (nesting). You must have TWO chars for
 ever level in. This is very vital.

 So for a stack that's 4 items large (lets 4 levels of nesting) you must do this in the FIRST line of the robot:

 . "#*-1-2-3-4"

 To call a subroutine, do something like this:

 goto "#sub"

 : "#sub"
 goto "#return"

 The subroutine's name must start with a #; to return to the next command after the call goto "#return"

 If you do goto #top it will return to the first subroutine's return position.

Hex representation of coutners:
 Now you can represent counters as hex from && and not just decimal. This is useful for the strings which require hex, like
 the partial char set loading or the colors in the message row. Simply do this:

 &+counter&

 For instance, if counter were 10...

 &counter& would put in 10, and &+counter& would put in a.

 Or this:

 &#counter&

 Which would but 0a, iow it will add a 0 if it's > 0x10. This is good for load char set, which needs
 a right justfied two digit hex number. The + version is good for * messages, which can't use something
 like ~0f.

Known bugs/issues:
 In Weirdness if you press enter after shooting the yo-yo the game will lock. (2.62b bug)
 In Caverns if you press enter on the town board it will initiate as if you bought something from one
  of the venders (2.62b bug, because of the KeyEnter label)
 After using alt+w to refresh the screen it's possible the mouse will work for half the screen.
 If you send a robot a subroutine while it is in the middle of a wait, the wait will be comprimised.


 Remember, this is beta. E-mail me problems.

- Exophase

 

 
  
