ZChecker v0.87: in-game actors view/debug/control/diagnosis tool for everyone

For Total Conversions and projects that don't otherwise fall under the other categories.
Forum rules
The Projects forums are only for projects. If you are asking questions about a project, either find that project's thread, or start a thread in the General section instead.

Got a cool project idea but nothing else? Put it in the project ideas thread instead!

Projects for any Doom-based engine (especially 3DGE) are perfectly acceptable here too.

Please read the full rules for more details.
User avatar
JSO_x
Posts: 3
Joined: Sat Sep 30, 2017 12:29 pm
Preferred Pronouns: He/Him
Operating System Version (Optional): Debian Linux

ZChecker v0.87: in-game actors view/debug/control/diagnosis tool for everyone

Post by JSO_x »

Greetings! "For everyone" means that this project will be useful for regular players, mod authors using Decorate, ZScript, ACS and DeHackEd, and map designers.

ZChecker is an in-game tool that primarily aims to facilitate easy and convenient debugging of actors, displaying real-time actor data and controlling them. In addition, the tool allows you to create actors by their partial names, view all actors from all loaded archives, sort them into categories, and even partially control the game world. The entire ZChecker, including its help information, is available in English and Russian.

ZChecker postulates (guarantees):
  1. No external object can change without explicit instruction from the user.
  2. The stability of the project is sufficient for it to be included in the permanent autoload list.
  3. The game’s performance with the tool running should always be comparable to the performance without it.
Minimal supported engine versions are GZDoom 3.3.1+, LZDoom 3.60+, and QZDoom 2.1+. A list of the other ports tested is available in Section 4.

This thread also has a FAQ on the tool (why you need it, how to use it, and so on).

There's a detailed breakdown of the basics below (and the game itself also has a detailed help screen available with a console command), but as they say, seeing is believing... Therefore:
ZChecker presentation
There is also a separate menu for commands, and at first it may be more convenient than working through the console. However, you should keep in mind that the menu is only a shell for a few important commands.
Spoiler: Other ZChecker videos


ZChecker consists of three major components:


=============== ─ ============================== ─ ===============
1. Informational panels (infopanels)

The main tool for real-time monitoring of actor properties (telemetry of actors). Each infopanel is linked to one actor, and up to three infopanels can be on the screen at the same time, accessible with numbers 1, 2 and 3, respectively. Each panel is divided into logical components. You can customize their visibility, order, and options specific to a certain feature (such as the number of rows in the inventory display). As of the latest version, v0.87, there are 15 infopanels, which include:
  • Various technical information like classname;
  • Position, speed, size;
  • Inventory;
  • Nearby states;
  • Actor pointers (e.g., AAPTR_TARGET);
  • Linked sectors;
  • TID, TID to hate, arguments;
  • …and other actor properties.
Spoiler: More screenshots
For the details about the addition command, “zcadd”, see section “2. Console commands (CCMDs)” and a link to the README file in it.

Linked menu “Information panel settings”:
  • Space, Enter, left, right, LMB — toggle visibility of panel parts.
  • 1, 2, 3 — toggle visibility of an element in a specific panel.
  • =, -, mouse wheel — move panels up/down.
  • RMB — move the cursor without changing options.




=============== ─ ============================== ─ ===============
2. Console commands (CCMDs)

ZChecker console commands greatly expand the engine's built-in suite:
  • Many added convenient options for working with actors, including improved replacements for some built-in commands.
  • Allow interaction with other parts of ZChecker (infopanels and the the Everything map).
  • Provide useful information about some static data that may be required during development.
  • Manipulate instances of the Thinker superclass (the base class for all objects that directly interact with the world).
All original ZChecker commands start with "zc". The main starting point is the "zchelp" console command (displays full in-game help information with examples), and the most frequently used commands are covered in the corresponding repository README section.
Spoiler: More screenshots
The <whom> parameter can be either an infopanel number ("1", "2", or "3"), a pointer to the player (keyword "self" or "s"), a target under the cursor ("lt" or "linetarget"), or a camera ("cam[era]"). By default, unless otherwise specified, targets whatever is under the mouse pointer.

In almost any place where the <class> is present, it can be specified by using a class mask. "*" (asterisk) will correspond to zero or more characters, "-" (hyphen) to one or more. For example, the class mask "z*man" without third-party modifications will be unambiguously recognized as "Zombieman", and "a-a-a-a" - as "ArachnotronPlasma". In case of ambiguity, you should choose an item from the list with a colon (like "*card:4" - choose the fourth option from the list of things ending in "card").





=============== ─ ============================== ─ ===============
3. The “Everything” map

Maps of the "Everything" kind are essentially a library, an exposition of all loaded actors. Attention: with some modifications the level may fail to start, if runtime errors occur in these modifications when loading with ZChecker! Whether they are inadvertent or intentional is not so important. You can either fix them yourself, or contact the author of that modification. Or us, the LLDM Doom Modding team, but with 98% probability we will redirect you to the author anyway :) .

All loaded actors are divided into twenty-odd categories: small monsters, large monsters, weapons, keys, passable decorations, shootable decorations, projectiles, player classes and so on.
Spoiler: More screenshots
Next to each actor there is an associated infoactor:
  • When you look at it, the class name of the linked actor appears, and the infoactor itself changes transparency.
  • Clicking on it will recreate the linked actor if the last one does not exist or if it is dead.
  • If the ZChecker console command is used on the infoactor, it will be passed to the linked actor.
  • infoactor’s color encodes the current state of the linked actor:
    • Green means that the linked actor exists and is alive.
    • Yellow means that the linked actor exists but is dead (has the +bCORPSE flag or health <= 0).
    • Red means that the linked actor does not exist.
  • Its height encodes the flags of the linked actor when it appears:
    • The top position, above eye level, means that the linked actor has a +SPAWNCEILING flag and is therefore created on the ceiling.
    • The middle position says that the actor is not affected by gravity (there are +bNOGRAVITY or +bNOINTERACTION flags).
    • In all other cases, the infoactor is in the lower position.
The Everything map adds some new CCMDs that start with “zcev”. All of them can be explained with the “zchelp zcev” command.

At the start of the level, all actor types appear on the map automatically. However, when debugging, it is often necessary to recreate the level without restarting it; for this purpose you can use command "zcev re[create]", or the corresponding item "Recreate actors" in the menu. There are also settings for what exactly will be created on the level:
Spoiler:



════════════ ─ ════════════≡════════════ ─ ════════════
Download & Credits


https://github.com/LLDM-Doom-Modding/ZChecker/releases/tag/v0.87 — the latest stable version, v0.87.
https://github.com/LLDM-Doom-Modding/ZChecker — main project repository.

All people involved in the development, as well as the people whose assets were utilized, are listed here: https://github.com/LLDM-Doom-Modding/ZChecker#credits.

Doom Power (Russian Doom Community) forum topic: http://i.iddqd.ru/viewtopic.php?t=2497.




=============== ─ ============================== ─ ===============
4. Advanced management. Technical and API for creating custom add-ons


Similar tool can't be done in Decorate/ACS, but you can run your Zandronum/DSDA-Doom/etc. mod in GZDoom to debug with ZChecker (as long as your mod works in GZDoom).

The project was tested on GZDoom 3.3.1, QZDoom 2.0, GZDoom 3.4.0, QZDoom 2.1pre, GZDoom 3.6.0, LZDoom 3.87a, LZDoom 3.87c, LZDoom 3.88, QZDoom g4.5.0, GZDoom 4.8.0, GZDoom 4.8.1, GZDoom 4. 9.1, GZDoom 4.10.0, GZDoom 4.11.0, and GZDoom 4.11.3.
Multiplayer was tested on GZDoom 4.8.2 with a 3.6-gigabyte modification, as well as on LZDoom 3.87c.

Subsequently, all information from here will be moved to a separate project guide.
Spoiler: Adding to autoexec, useful extra aliases, and API

* * *

Have fun modding!

And Happy New Year!
Last edited by JSO_x on Mon Feb 05, 2024 3:18 am, edited 2 times in total.
User avatar
Ron_Dallas
Posts: 17
Joined: Sun Nov 06, 2022 2:20 am
Operating System Version (Optional): Windows 10

Re: ZChecker v0.87: in-game actors debug/control tool for everyone

Post by Ron_Dallas »

Yoooo, lets go!
User avatar
JSO_x
Posts: 3
Joined: Sat Sep 30, 2017 12:29 pm
Preferred Pronouns: He/Him
Operating System Version (Optional): Debian Linux

Re: ZChecker v0.87: in-game actors debug/control tool for everyone

Post by JSO_x »

Noticed that forget to update a version string in the tool files ("v0.86" to "v0.87"); otherwise everything is fine, previously downloaded version is actually release and full. I've updated the repository archive anyway.




* * *

In the next week I'll post a FAQ. "How ZChecker can be useful for regular players", "Can the tool be used for projects under Zandronum / DSDA-Doom / other port", "How to debug projects more effective" and other related questions...
User avatar
JSO_x
Posts: 3
Joined: Sat Sep 30, 2017 12:29 pm
Preferred Pronouns: He/Him
Operating System Version (Optional): Debian Linux

ZChecker v0.87 FAQ

Post by JSO_x »

=============== ─ ============= FAQ ============ ─ ===============
Spoiler: How compatible is ZChecker (with other modifications, with old versions, ...)?
Spoiler: Why ZChecker for common players/reviewers?
Spoiler: Why do mappers (map testers) need ZChecker?
Spoiler: Why do modders need ZChecker?
Spoiler: Can it be used for mods for Zandronum, DSDA-Doom, Eternity and so on?
Spoiler: My mod started to slow down. How to debug it more efficiently?
Spoiler: What are some built-in commands that work well with ZChecker?
Spoiler: My [complex actor with a lot of states] is broken and I can't find the cause. ZChecker will help?
Spoiler: The map "Everything" does not start/hang.
Spoiler: Can I create a copy of linetarget actor on "Everything"?
Spoiler: What are your settings?

Return to “TCs, Full Games, and Other Projects”