From ef74f86ce2d853dd05807ffd791bfe30247a3762 Mon Sep 17 00:00:00 2001
From: Alibek Omarov <a1ba.omarov@gmail.com>
Date: Thu, 10 Nov 2022 12:37:47 +0300
Subject: [PATCH] Documentation: restore enttools docs from old engine wiki

---
 Documentation/entity-tools.md | 150 ++++++++++++++++++++++++++++++++++
 1 file changed, 150 insertions(+)
 create mode 100644 Documentation/entity-tools.md

diff --git a/Documentation/entity-tools.md b/Documentation/entity-tools.md
new file mode 100644
index 00000000..8a8a16cf
--- /dev/null
+++ b/Documentation/entity-tools.md
@@ -0,0 +1,150 @@
+# There are few new commands availiable in xash3d fork:
+
+## Commands:
+### ent_create
+Create entity with specified classname and key/values
+
+`ent_create <classname> <key> <value> <key> <value> ...`
+
+for example:
+
+`ent_create monster_zombie targetname zomb1`
+
+after creating entity, ent_last_xxx cvars are set to new entity and ent_last_cb called, look at ent_getvars description
+
+### ent_fire
+
+Make some actions on entity
+
+`ent_fire <pattern> <command> <args>`
+Availiavle commands:
+* Set fields (Only set entity field, does not call any functions):
+   * health
+   * gravity
+   * movetype
+   * solid
+   * rendermode
+   * rendercolor (vector)
+   * renderfx
+   * renderamt
+   * hullmin (vector)
+   * hullmax (vector)
+* Actions
+   * rename: set entity targetname
+   * settarget: set entity target (only targetnames)
+   * setmodel: set entity model (does not update)
+   * set: set key/value by server library
+       * See game FGD to get list.
+       * command takes two arguments
+   * touch: touch entity by current player.
+   * use: use entity by current player.
+   * movehere: place entity in player fov.
+   * drop2floor: place entity to nearest floor surface
+   * moveup: move entity to 25 units up
+   * moveup (value): move by y axis relatively to specified value
+* Flags (Set/clear specified flag bit, arg is bit number):
+   * setflag
+   * clearflag
+   * setspawnflag
+   * clearspawnflag
+
+### ent_info
+Print information about entity by identificator
+
+`ent_info <identificator>`
+
+### ent_getvars
+Set client cvars containing entity information (useful for [[Scripting]]) and call ent_last_cb
+
+`ent_getvars <identificator>`
+
+These cvars are set:
+```
+ent_last_name
+ent_last_num
+ent_last_inst
+ent_last_origin
+ent_last_class
+```
+
+### ent_list
+Print short information about antities, filtered by pattern
+
+`ent_list <pattern>`
+
+## Syntax description
+
+### \<identificator\>
+
+* !cross: entity under aim
+* Instance code: !\<number\>_\<seria\l>
+ * set by ent_getvars command
+* Entity index
+* targetname pattern
+
+### \<pattern\>
+
+Pattern is like identificator, but may filter many entities by classname
+
+### (vector)
+
+used by ent_fire command. vector means three float values, entered without quotes
+
+### key/value
+
+All entities parameters may be set by specifiing key and value strings.
+
+Originally, this mechanizm is used in map/bsp format, but it can be used in enttools too.
+
+Keys and values are passed to server library and processed by entity keyvalue function, setting edict and entity owns parameters.
+
+If value contains spaces, it must be put in quotes:
+
+`ent_fire !cross set origin "0 0 0"`
+
+## Using with scripting
+
+ent_create and ent_getvars commands are setting cvars on client
+
+It can be used with ent_last_cb alias that is executed after setting cvars.
+
+Simple example:
+
+```
+ent_create weapon_c4
+alias ent_last_cb "ent_fire \$ent_last_inst use"
+```
+
+Use weapon_c4 after creating it.
+
+Note that you cannot use many dfferent callbacks at the same time.
+
+You can set entity name by by pattern and create special script, contatning all callbacks.
+
+Example:
+
+example.cfg
+```
+alias ent_last_cb exec entity_cb.cfg
+ent create \<class\> targetname my_ent1_$name
+ent_create \<class\> targetname my_ent2_$name
+```
+entity_cb.cfg
+```
+if $ent_last_name == my_ent1_$name
+:(ent1 actions)
+if $ent_last_name == my_ent2_$name
+:(ent2 actions)
+```
+Note that scripting cannot be blocking. You cannot wait for server answer and continue. But you can use small scripts, connected with ent_last_cb command. The best usage is user interaction. You can add touch buttons to screen or call user command menu actions by callbacks.
+##  Server side
+
+To enable entity tools on server, set sv_enttools_enable to 1
+
+To change maximum number of entities, touched by ent_fire, change sv_enttools_maxfire to required number.
+
+To enable actions on players, set sv_enttools_players to 1.
+
+To enable entity tools for player by nickname, set sv_enttools_godplayer to nickname. Useful to temporary enable from rcon.
+
+To prevent crash on some actions, set host_mapdesign_fatal to 0
\ No newline at end of file