More prvm_* examples
[xonotic/xonotic.wiki.git] / Programming-Tips.md
1 ### Debug prints
2
3 Use `con_notify 4` together with `LOG_INFOF("my_var: %s", my_var);` (`%s` string, `%f` float, `%d` integer, `%v` vector) to see debug output without opening the console. Type `con_notify` and press `<TAB>` to see descriptions and more options (or use `apropos con_notify`).
4
5 You can draw text anywhere on the map using `debug_text_3d(world_coords, message);` from `common/debug.qh`.
6
7 ### Multiple clients + clean config
8
9 If you need 2 players for debugging, you can launch another client locally:
10  - use -sessionid (e.g. `./all run -sessionid testing`) to keep your config
11  - use -userdir (e.g. `./all run -userdir ~/.xonotic-testing +name tester +cl_allow_uid2name 0`) to get a clean config (`+cl_allow_uid2name 0` to avoid an annoying popup). You can set whatever cvar on start with `+cvar_name value`.
12
13 ### Testing with bots
14
15 You can prevent bots from firing with `bot_nofire 1` or stop them completely with `bot_cmd * pause` (unstop them with `bot_cmd * continue`). With `sv_cheats 1` (takes effect next match), you can drag them around (default key V or 'drag object' in menu).
16
17 Note that `sv_cheats 1` prevents bots from spawning in the campaign (should you decide to put it in your `autoexec.cfg` and later wonder why the campaign is broken).
18
19 ### Debugging
20
21 Useful commands to debug qc code:
22 ```
23 prvm_breakpoint : marks a statement or function as breakpoint (when this is executed, a stack trace is printed); to actually halt and investigate state, combine this with a gdb breakpoint on PRVM_Breakpoint, or with prvm_breakpointdump; run with just progs name to clear breakpoint
24
25 prvm_edict    : print all data about an entity number in the selected VM (server, client, menu)
26 prvm_edictget : retrieves the value of a specified property of a specified entity in the selected VM (server, client menu) into a cvar or to the console
27 prvm_edicts   : prints all data about all entities in the selected VM (server, client, menu)
28 prvm_edictset : changes value of a specified property of a specified entity in the selected VM (server, client, menu)
29 prvm_edictwatchpoint : marks an entity field as watchpoint (when this is executed, a stack trace is printed); to actually halt and investigate state, combine this with a gdb breakpoint on PRVM_Breakpoint, or with prvm_breakpointdump; run with just progs name to clear watchpoint
30
31 prvm_global    : prints value of a specified global variable in the selected VM (server, client, menu)
32 prvm_globalget : retrieves the value of a specified global variable in the selected VM (server, client menu) into a cvar or to the console
33 prvm_globals   : prints all global variables in the selected VM (server, client, menu)
34 prvm_globalset : sets value of a specified global variable in the selected VM (server, client, menu)
35 prvm_globalwatchpoint : marks a global as watchpoint (when this is executed, a stack trace is printed); to actually halt and investigate state, combine this with a gdb breakpoint on PRVM_Breakpoint, or with prvm_breakpointdump; run with just progs name to clear watchpoint
36 ```
37
38 Examples:  
39 Print to console origin of entity number 1: `prvm_edictget server 1 origin`  
40 Save to a cvar origin of entity number 1: `prvm_edictget server 1 origin my_cvar`  
41 Set a custom origin for entity number 1: `prvm_edictset server 1 origin "100 200 0"`  
42
43 Print to console vid_conheight client global: `prvm_edictget client vid_conheight`
44
45 "Break" on statement: `prvm_breakpoint server 12345`  
46 "Break" on function: `prvm_breakpoint server ClientConnect`  
47 Watch for global change: `prvm_globalwatchpoint server time`  
48 Watch for entity field change: `prvm_edictwatchpoint server 1 health`  
49
50 There can be only one of each kind. To clear, do:
51 ```
52 prvm_breakpoint server
53 prvm_globalwatchpoint server
54 prvm_edictwatchpoint server
55 ```