[Lachesis]

Can you fix the help file entry for the counter "KEY" to reflect:

1) It is not read-only; you can write values into it
2) It retains its value after the key is released
3) It is not precisely the same as KEY_PRESSED -- it returns uppercase letter values rather than lowercase values

Thanks :>

[Graham]

I just noticed this contradiction tonight;

in the "Counters, Built-in Counters and Local Counters" section of the "Robotic Reference Manual", it says:

"Local, (counters) which are different for each Robot and are only available to read by that Robot"

Whereas the "Robotic Usages That Should be Avoided" section reads:

"the local counters can be written to and read by other robots as well (using the r&id&.local# counter form)."

[Terryn]

Yeah, point. I'll re-write that bit.

Thanks for the heads-up.

EDIT: For the post below, I'll change that to rN to remove any ambiguities. It was implied that "&id&" meant whatever the desired Robot ID is, with no parenthetical ampersands, but I definitely see how that's ambiguous. I'll just do the aforementioned change and include a link to the relevant counter section.

[Graham]

No problem. Also it worked correctly for me without the ampersands in the example
(r&5&.local) returned 0
(r5.local) returned the local counter value

[Terryn]

(Jun 29 2017) CHANGED SINCE 2.84C HELPFILE:

-Added section on board scan / cycles.
-Added a bit more to the Sprites section (besides the new additions).
-The formula for MZX_SPEED is now given in its counter description.
-Added mention of setting commands to max to bad practices.
-Noted that KEY retains its value even when the key is released.
-the # prefix for reading counter values was undocumented; fixed.
-Added question about game protection to FAQ.
-Corrected max size of board/vlayer.
-Added section on the updater.
-Noted VOLUME #'s limitation to the current board.
-Corrected sound frequency given in sound example.
-Other minor fixes and style changes.

[Terryn]

(Jul 16 2017) CHANGED SINCE 2.90 HELPFILE:

-Documented all relevant additions since 2.90.
-Re-wrote the palette editor section to fit my stodgy, stilted style and to clarify a few minor points, in addition to documenting 2.90b's additions.
-Documented PLAY_GAME counter (I'd forgotten, sorry).
-Action of sprN_overlay regarding unbound sprites documented (by Lancer, style edits forthcoming).
-Mentioned the specific case of using blank strings for breakpoints.
-Key shortcuts for the Robotic debugger window weren't detailed, just for the breakpoint editor. Corrected.
-The rest of the KEY inaccuracies pointed out in this thread are corrected.

[Lachesis]

Ctrl+Arrows isn't documented. During the copy block (repeated) action, after you place the first block, you can use Ctrl+Arrows to move the width of the block horizontally or the height of the block vertically. This makes tiling blocks easier. When the block action is canceled with escape, Ctrl+Arrows is disabled.

(note as of GIT 640f6fd, Ctrl+Arrows doesn't require a first block to be placed and works for all block actions with a placement step)

[Lachesis]

In the help section for the Game Settings menu:

Quote

In addition to these settings, one can change the current scaling shader if running MegaZeux with the GLSL renderer. Unlike the rest of these settings, this setting is applied globally.

Actually, every setting in this menu aside from MZX speed (i.e. the audio toggles and volume sliders) is global.

[Lachesis]

This was true for 2.80X strings, but 2.81+ strings don't work this way: $str will instead be set to "Long". However, if you set "$str+0#4" instead of "$str#4", then this code works.

The bit a couple of paragraphs before about an offset not decreasing the length of the string makes the actual behavior seem intentional.

[Terryn]

(Nov 22 2017) CHANGED SINCE 2.90B HELPFILE:

-Operation precedence in expressions is detailed.
-Handling of whitespace in expressions is noted.
-Instructions for selecting a character block in the char editor were wrong; corrected.
-Corrected string splicing example (it was correct in earlier MZX versions but not when added to the help).
-Noted F2/F3's changed actions in interactions other than single char -> single char.
-SPRn_CCHECK behavior explained in greater detail, including the previously-left-out 3 setting.
-Ctrl+Dir was only documented in overlay block info; added to board block info.
-Corrected tertiary example.
-Noted char 32's action in sprites.
-SPRn_TCOL explained in greater detail.
-Corrected info on F2 menu settings (some settings were erroneously implied to be local).
-Removed mentions of the 14-number codes once produced by the char editor; provided a now-needed explanation for the CHAR EDIT input format.
-Described action of TAKE # [item] when player lacks the required number.
-Gave caveat about using TRADE with health/lives possibly resulting in having 0 of either afterwards.
-Other minor style edits and fixes.

[Terryn]

(Sep 17 2018) CHANGED SINCE 2.91 HELPFILE:

-Fixed an error involving loading MZMs from subdirectories.
-The intiial values for fread_pos/fwrite_pos, as well as their values when no file is loaded, are now explicitly mentioned.
-The help file treats subdir reading as its own command type now instead of merely mentioned as a footnote.
-Documented the hotkeys that launch the editor into a new project using MZX's old default behavior.
-Noted that local counters can be set as watchpoints.
-A mention of the editor's old behavior when char editing in SMZX modes was accidentally left in; removed.
-Clarified rN.<counter> descriptions to note that the angle brackets are to visually isolate the counter in the description and are not to be included when using.
-Clarified ccheck actions with unbound sprites.
-Minor modernity/phrasing fixes.

[Terryn]

(Nov 14 2018) CHANGED SINCE 2.91F HELPFILE:

-Several clarifications in Sprites section (listed sprites as global; mentioned vlayer referencing; described what refx/refy referred to; noted what happened when ref chars change; clarified that any one unbound sprite is limited to 256 chars, but another unbound sprite can concurrently display a different 256 chars).
-Noted background color 0's ability to take on the background color of anything under it.
-Documented configuring (extended) macros.
-Documented import/export of characters by character tiles.
-Noted standalone game's actions regarding multiple counters (in the counters' sections).
-Noted games being able to block the escape menu and how to launch if blocked.
-Mentioned application of the newline character in the description for the * "string" command.
-Mentioned the editor's inability to load runtime Robots in MZMs.
-Endgame teleport behavior was mentioning the old behavior; corrected to accurately describe its current behavior.
-Noted color codes applying to board names.
-Fixed incorrect descriptions of add board behavior (what happens after the board is added).
-List of KEY? label special keys made more complete.
-Corrected errors in the format for sfx section (note default and middle c).
-Corrected note about using REL with COPY commands: it was describing a buggy action (and even then wasn't fully accurate).
-Added a play tip about shooting enemies that spit fire.
-Noted mouse wheel actions in the editor.
-Added more detail about world decryption.
-Corrected damage details of seekers (it incorrectly assumed 10 before, when their damage can be changed).
-Added Sprites, Board Name Length and Macro Length to limitations section.
-Noted action of IF Sprite checks for multi-char sprites.
-Noted status counter name limit.
-Mentioned the animation frame side-effect of setting the char_id of some things to (char) 255.
-Added mentions of ability to swim in lava/goop to shark description.
-Made descriptions of ice, fire and lava more detailed.
-Made description of items cheat more accurate.
-Described TOUCH attempts when the player is locked.
-Mentioned THUD and EDGE's tendency to constantly trigger.
-Added GIVE lines and an IF statement as new elements in the last tutorial robot's code.
-Noted the difference between ZZT and MZX in transitioning between boards.
-Lots of style changes, other minor fixes and clarifications.

[Terryn]

(Feb 20 2019) CHANGED SINCE 2.91H HELPFILE:

-Clarified what reference characters are in the Sprite section a bit further.
-Described the usage of WAIT 1 / CYCLE 1 explicitly for cycle ending in the cycles and commands section.
-Re-wrote bits of SMZX 2/3 section to clarify the difference between actual colors and color assignment.
-Noted fades/lack of fading for methods of board transitions.
-Mentioned KEYn's lack of autorepeat stall.
-Previous text implied that only chars changed (and not colors) when reference chars were changed; corrected.
-Mentioned file ops using strings in more places and in better detail.
-Noted what creatures can move over lava/goop, instead of just noting that sharks can.
-Corrected a typo in one section that named KEY_CODE as KEYCODE.
-Fixed minor error in KEY? description (alphanumeric is written instead of alphabetic regarding shifted chars).
-Removed specific amounts of damage from creature descriptions, as these can be changed.
-Made Banish/Summon effect descriptions more detailed.
-Fixed F4 and F5 being undocumented in the char editor section.
-Removed outdated method of changing ui colors.
-Suggested standalone mode as a minor tamper prevention device (for those few who still worry about that).
-Other fixes and formatting changes too minor to list here.

[Terryn]

(Jul 22 2019) CHANGED SINCE 2.91J HELPFILE:

-Moderately re-wrote collision subsection in the Sprites tutorial (made far less vague, fixed old text that implied default collision boxes, noted sprN_clist checking method).
-Added paragraph explaining (default) sprite draw order in the Sprites tutorial.
-Wrote up the new version additions.
-Removed incorrect description of static sprite collision detection.
-Explicitly mentioned that label sends interrupt WAIT periods under WAIT #'s description.
-Denoted exactly which classes of counters a counter save contains.
-Fixed both a vaguely-worded description and an outright incorrect description of spr_num's functions.
-Clarified descriptions for the *VIEW command family to note their changes as instantaneous.
-Mentioned the ability to mimic Custom objects by setting an object type's char to 255 in the global chars tables.
-Added question about sound volume control in FAQ section (due to being asked about this more than once).
-Replaced method of finding file length with the easier and clearer method introduced in 2.92.
-Noted that SPRn_SETVIEW is a one-time view jump and not a permanent follow.
-Added examples of using subdirectories in file access section.
-Corrections and clarifications in sound section (explaining & and sample rate, explaining mzx's odd octave numbering, correcting erroneous middle c change and two numerical typos).
-Noted the message line's centering action as default.
-Gave offsetting a string with negative values an example to clarify syntax.
-Added full descriptions of the FREAD/FWRITE/FREADn/FWRITEn actions in the counter section for consistency.
-Corrected COMMANDS_STOP naming typos in its description.
-Noted sprN_cx / sprN_cy / sprN_tcol / multiplier / divider / c_divisions default values under their counter descriptions.
-Removed one last outdated mention of being able to edit the protected palette in MZX (in the SMZX_R/G/B counters description) and one last implied mention (in CURRENT_COLOR counter description).
-Mentioned the CHAR counter's ability to select characters in extra charsets.
-Added detail to energizer description.
-Noted SMZX_MODE actions on being set to values outside 0-3.
-Minor edits improving term / layout consistency.

[Graham]

Thank you for your continued diligence in keeping the help file as accurate as possible Terryn.

[Terryn]

(Sep 23 2019) CHANGED SINCE 2.92 HELPFILE:

-Corrected description of SPR_YORDER.
-Added FAQ question about extended graphics and renderers.
-Re-wrote a section in beginning of Nondescript Play Tips to seem less discouraging.
-Fixed line showing the inability to nest ampersands.
-Noted that player locks can also prevent related default messages from displaying.
-Noted that bombs can ignite on touch depending on board settings.
-Mentioned the global's inability to be found by actual checks at (-1,-1).
-Mentioned Reality Tracker under FAQ question about making module files.
-Listed bounds for SMZX_{R/G/B}n counters.

[Terryn]

(May 08 2020) CHANGED SINCE 2.92B HELPFILE:

-I added a symbol to note commands that typically end a cycle next to those commands in the command reference. This was a help file feature that was in MZX 1.XX help but was removed for some reason for 2.XX help.
-Added a rudimentary example of maintaining a high scores file in the file access section.
-Explained how KEY_RELEASE works (as opposed to not doing that).
-Noted that the player stops movement when trying to fire.
-Fixed false statement in the Command Syntax that stated char 0 could not be used as a single char.
-The Sprite tutorial now explains how to deactivate a sprite.
-Fixed errors in the Command Syntax with example numbers.
-Previous descriptions of keys/locks didn't say what had to match in order to unlock a lock; this has been added.
-Suggested using multi-line * messages in FAQ question about spaces and the overlay.
-Gave more detail about status counters.
-Noted freezetime's/slowtime's effects on the damage timer and precisely when the damage timer ticks down.
-Mentioned Show Robots and Robotic search in code searching suggestion.
-Edited savegame compatibility note to be more current.
-digitalmzx.net: "It's Dot Com".
-Clarified ROTATECW/ROTATECCW actions.
-Minor edits for better clarity and accuracy.

[hseiken]

Much thanks to the documentation crew.

[Terryn]

(Jan 01 2024) CHANGED SINCE 2.92D HELPFILE:

-Added documentation for 2.93's new features.
-Described how to use large numbers near the beginning of the Counters section. This was already done in several other places, such as the FAQ and expressions sections, but not here.
-Added an unfortunately-necessary question about which MZX version to use at the very top of the FAQ.
-The MZM section now mentions how to import an MZM in the editor.
-Explained how to read an MZX world's parent directory with FREAD_OPEN.
-Re-worked Sprites tutorial a bit to better explain sprite reference characters.
-Modest KEY* counter section rework (noted 0 when no key held for KEY_PRESSED/KEY_CODE, made KEY_CODE's attributes more explicit, mentioned KEY/KEY_PRESSED/KEY_CODE only return the value of the last key pressed when multiple keys are pressed/held at once, explicitly noted multiple KEYn-class counters (and new KEY_PRESSEDn-class counters) can report held values at a time, removed outdated mention of joystick codes now that actual support is in).
-IF Sprite_colliding command description is much more accurate now.
-* "string" section beefed up to mention its color cycling, color code compatibility, and duration.
-Finally added a type-based command reference list to go with the alphabetic one. Categories are, in this order: Flow & Branching / General Color & Char / Item Color & Char / Counter & String Manip / Music & Sound / Textbox & Message Row / Board Placement & Copy / Overlay / View / Other Board / Player Control & Item / Self Movement & Attack / Other Self / Misc. (These are not the exact names, just simplifications for this post.) The actual descriptions for each are not mirrored in this arrangement, just the command listing.
-Chunked TOC and Reference Manual links into sections to make more readable. (Apologies in advance for any muscle memory problems this causes. :S)
-Described how counters typically act when attempts to go past their ranges are made.
-The REL section of help now begins with a note suggesting less-deprecated methods.
-Documented how SPRn_OFF shows a sprite's on/off status.
-Made clearer that NODIR/ANYDIR only work with certain condition checks (not with e.g. IF or GO).
-Explained how board linking via directional exits acts in more detail.
-Described results of invalid actions for all of the layer reading/manip counters. ("BOARD_ID", "OVERLAY_COLOR", "UPRx,y", "VCHx,y", etc.)
-Pointed to the wiki's compilation/debug build instructions in the relevant FAQ section.
-MZMs saved from the board are properly listed as board type.
-Noted relevant shot/bomb reactions for Gems, Coins, Pouches and Chests. (Guess ZZT legacy assumptions explain the prior lack of note for Gems, if not the rest?)
-Stated how large hibomb/lobomb explosions are.
-Corrected improper description of the PUSHED label's trigger, and explained what happens when a push fails to move a Robot.
-Properly marked WAIT MOD FADE and WAIT PLAY as cycle-ending.
-Described Alt+C function in scroll editor.
-Mentioned BOARD [dir]'s unique ability to link board exits to the title screen.
-Noted same-board TELEPORT PLAYER actions.
-Mentioned save slots.
-Described how COPYROBOT "Name" acts when multiple Robots with this name are present.
-Other style changes, minor fixes, and minor clarifications.

[Terryn]

(Sep 10 2024) CHANGED SINCE 2.93 HELPFILE:

-Robotic command type listing improvements (now leads with jump list by type, better organization of the IF command cluster, better placement of INPUT STRING/CLIP INPUT).
-Watchpoint section now properly mentions the ability to watch strings, now explains what is shown when one is triggered, and describes how to read the global Robot's local counters.
-Corrected order of operations section to mention ternary/unary precedence.
-SPRn_OFFONEXIT now mentioned in Sprite tutorial.
-Re-grouped Sprite and String counters.
-Differentiated between the title screen (a mode) and title board (a location) where necessary.
-Stated that ROBOT_ID counter values are directly derived from Robot parameters under ROBOT_ID counter description.
-Better described SPR_CLISTn counter values.
-Better described the *_NAME string counter actions, and mentioned that unlike INPUT, they can't be directly displayed.
-Provided more detail on the reverse send quirk.
-Detailed how Stairs/Cave/Whirlpool determine destination.
-Better described the INPUT counter's actions.
-Basic PUT and PUT PLAYER commands have a more accurate description.
-Noted explosion effects on creatures (including dragons' partial explosion resistance).
-Listed score values for shooting creatures and collecting rings/potions.
-The Board Counters section now leads with proper descriptions of BOARD_X and BOARD_Y, and corrects docs on how BOARD_COLOR/BOARD_CHAR work on OOB readings.
-Added mention of c0x transparency quirk in overlay section. (It was in the description for [color], but not here.)
-Fully described meaning of both numbers in COLOR INTENSITY # # PERCENT command.
-Said what exactly vlayer-to-board and overlay-to-board copies place.
-Gave audio-related built-in counters their own section.
-The Size field for of import of partials/sets was not mentioned before, oops. Added.
-Mentioned what OpenGate's parameter field actually does. (Lazer field TBA? It seems messed-up from first glance )
-Offhand mention of title screen's behavior of wiping values on world load under SWAP WORLD description, as there was seemingly no better place to mention it.
-Mentioned pain messages and sounds still triggering for taking 0 damage from defaults.
-Refined Robotic Tutorial explanatory text in some examples.
-Other minor style fixes and clarifications.

[hseiken]

Terryn, on 12 September 2024 - 01:11 PM, said:

(Sep 10 2024) CHANGED SINCE 2.93 HELPFILE:

-Robotic command type listing improvements (now leads with jump list by type, better organization of the IF command cluster, better placement of INPUT STRING/CLIP INPUT).
-Watchpoint section now properly mentions the ability to watch strings, now explains what is shown when one is triggered, and describes how to read the global Robot's local counters.
-Corrected order of operations section to mention ternary/unary precedence.
-SPRn_OFFONEXIT now mentioned in Sprite tutorial.
-Re-grouped Sprite and String counters.
-Differentiated between the title screen (a mode) and title board (a location) where necessary.
-Stated that ROBOT_ID counter values are directly derived from Robot parameters under ROBOT_ID counter description.
-Better described SPR_CLISTn counter values.
-Better described the *_NAME string counter actions, and mentioned that unlike INPUT, they can't be directly displayed.
-Provided more detail on the reverse send quirk.
-Detailed how Stairs/Cave/Whirlpool determine destination.
-Better described the INPUT counter's actions.
-Basic PUT and PUT PLAYER commands have a more accurate description.
-Noted explosion effects on creatures (including dragons' partial explosion resistance).
-Listed score values for shooting creatures and collecting rings/potions.
-The Board Counters section now leads with proper descriptions of BOARD_X and BOARD_Y, and corrects docs on how BOARD_COLOR/BOARD_CHAR work on OOB readings.
-Added mention of c0x transparency quirk in overlay section. (It was in the description for [color], but not here.)
-Fully described meaning of both numbers in COLOR INTENSITY # # PERCENT command.
-Said what exactly vlayer-to-board and overlay-to-board copies place.
-Gave audio-related built-in counters their own section.
-The Size field for of import of partials/sets was not mentioned before, oops. Added.
-Mentioned what OpenGate's parameter field actually does. (Lazer field TBA? It seems messed-up from first glance /> )
-Offhand mention of title screen's behavior of wiping values on world load under SWAP WORLD description, as there was seemingly no better place to mention it.
-Mentioned pain messages and sounds still triggering for taking 0 damage from defaults.
-Refined Robotic Tutorial explanatory text in some examples.
-Other minor style fixes and clarifications.

I noticed most of these changes without realizing it. I thought for a moment, 'damn, I must have missed this before', but looking at this list, it's stuff that I didn't miss, but wasn't in there or wasn't thourough enough for dummies like myself. Keep on fighting the good fight. Good documentation is hard to find for anything these days. I can't promise I'll be a better user with great documentation, but I at least will know enough to know what I don't know and how to know it better.

[Terryn]

(Feb 28 2025) CHANGED SINCE 2.93B HELPFILE:

-Counter interpolation was mentioned several times, but never directly defined. Fixed.
-Better described ccheck actions (how standard sprites apply values, how unbound sprites apply values, how values are applied against foreground, how ccheck 1 deals with edited char 32s and ccheck 2 doesn't; also added missing comment about ccheck 3 making checks pixel-based to tutorial section).
-Clarified collision boxes in sprite tutorial by describing them as relative to the sprite and listing their default locations.
-Clarified mentions of INPUT in several ways (explicitly noted that INPUT as a counter is different from &INPUT& in messages, noted what happens when INPUT as a counter is interpolated, removed misleading aside from counter interpolation section of &INPUT& usage in messages).
-Changed editor keys section to prefer the term "thing in the buffer" over "current thing" to try to prevent confusion with the thing currently under the cursor. (One line, now fixed, outright called the thing under the cursor the current thing.)
-Mentioned that 256 numerically represents p??.
-Changed IF SPRITE_COLLIDING listing from c?? to cNN and more carefully differentiated between c?? and non-c?? actions.
-Mentioned extended char number access for all relevant commands and noted their extended range under the definition for [char].
-Some UI help that had only listed or assumed one method of performing an action (usually assuming mouse by stating "click" instead of the term "select") when both mouse/kb could perform it now mention both.
-Mentioned scrollwheel and middle click actions in the editor.
-Noted TAKE HEALTHS actions on playerhurt label checks and energized players.
-Directly stated that text spaces on the overlay yield character 32s.
-Gave a quick intro statement in the Nondescript Play Tips section.
-Noted that a sprite's counter lists only show up in the debugger if any of that sprite's counters are set.
-Other minor corrections and form edits.