[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.