From 199e226758e3a65f71606edd3294756aaf0270fb Mon Sep 17 00:00:00 2001 From: Vladimir Date: Mon, 11 Nov 2024 10:29:24 +0300 Subject: [PATCH] Documentation updates and additions (#1875) * Documentation: actualize and prettify entity tools instructions * Documentation: added article about NAT bypass feature * Documentation: updated GoldSrc protocol support article --- Documentation/entity-tools.md | 150 --------------------- Documentation/extensions/entity-tools.md | 152 ++++++++++++++++++++++ Documentation/goldsrc-protocol-support.md | 5 +- Documentation/nat-bypass-usage.md | 32 +++++ 4 files changed, 187 insertions(+), 152 deletions(-) delete mode 100644 Documentation/entity-tools.md create mode 100644 Documentation/extensions/entity-tools.md create mode 100644 Documentation/nat-bypass-usage.md diff --git a/Documentation/entity-tools.md b/Documentation/entity-tools.md deleted file mode 100644 index 8a8a16cf..00000000 --- a/Documentation/entity-tools.md +++ /dev/null @@ -1,150 +0,0 @@ -# There are few new commands availiable in xash3d fork: - -## Commands: -### ent_create -Create entity with specified classname and key/values - -`ent_create ...` - -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 ` -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 ` - -### ent_getvars -Set client cvars containing entity information (useful for [[Scripting]]) and call ent_last_cb - -`ent_getvars ` - -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 ` - -## Syntax description - -### \ - -* !cross: entity under aim -* Instance code: !\_\ - * set by ent_getvars command -* Entity index -* targetname 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 \ targetname my_ent1_$name -ent_create \ 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 diff --git a/Documentation/extensions/entity-tools.md b/Documentation/extensions/entity-tools.md new file mode 100644 index 00000000..a17dbd24 --- /dev/null +++ b/Documentation/extensions/entity-tools.md @@ -0,0 +1,152 @@ +# Entity tools + +For some features described below, you need to enable [console scripting](https://github.com/FWGS/xash3d-fwgs/blob/master/Documentation/extensions/console-scripting.md) with command `cmd_scripting 1` in console. +To get more information about it, check another according page related to console scripting. + +## Commands description + +### ent_create +Create entity with specified classname and key/values. + +`ent_create ...` + +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 + +Makes some actions on entity. + +`ent_fire ` + +#### Available 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 ` + +### ent_getvars +Set client cvars containing entity information (useful for [scripting](extensions/console-scripting.md)) and then calls ent_last_cb. + +`ent_getvars ` + +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 ` + +## Syntax description + +#### \ +* !cross: entity under aim +* !\_\: instance code +* Set by ent_getvars command +* Entity index +* Targetname 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 different 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 \ targetname my_ent1_$name +ent_create \ 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 configuration + +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. diff --git a/Documentation/goldsrc-protocol-support.md b/Documentation/goldsrc-protocol-support.md index 9e2cbd4f..b1e4f227 100644 --- a/Documentation/goldsrc-protocol-support.md +++ b/Documentation/goldsrc-protocol-support.md @@ -6,9 +6,10 @@ For connecting to GoldSrc-based servers, use this command: connect ip:port gs ``` -But keep in mind, there are requirement for server to be able to accept connections from Xash3D-based clients: it should accept HLTV connections. +But keep in mind, there are requirement for server to be able to accept connections from Xash3D-based clients: it should use Reunion or Dproto. Without this requirement, you will just get "Steam validation rejected" error on connecting. That is because proper authorization with Steam API is not implemented in engine yet (but we have plans on it). -In case of ReHLDS with Reunion plugin, by default it rejects HLTV clients. But connections from HLTV can be easily enabled in `reunion.cfg` file. +Also, we encountered that some GoldSrc-based servers are recognizing Xash3D clients as "fake clients" and banning/kicking them. Maybe this problem will be +solved along with better compatibility with GoldSrc behavior, but may be not - we don't know logic behind this fake client checks. diff --git a/Documentation/nat-bypass-usage.md b/Documentation/nat-bypass-usage.md new file mode 100644 index 00000000..fabf363b --- /dev/null +++ b/Documentation/nat-bypass-usage.md @@ -0,0 +1,32 @@ +# NAT bypass feature in Xash3D FWGS +Since IPv6 not as widespread as we would like, NAT (Network Address Translation) still being actively used by many internet service providers in an attempts to +mitigate IPv4 addresses exhaustion. In short, they uses one IPv4 address and doing some tricks with ports to represent many other users behind this address. + +But this leads to a problem for users: they cannot accept direct +incoming connections anymore. This means that if you are behind provider's NAT and will try to setup Xash3D FWGS server - nobody will be able to connect to it, +and the server will not show up in servers public list. + +## Is it possible to avoid this problem? +In most cases, it is possible to bypass NAT with UDP hole punching, and Xash3D FWGS uses this method too. But this method is not 100% guaranteed to work - it depends +on NAT configurations on both server and client side, and there is no way to control it. + +First of all, server should not be behind symmetric NAT. You can check your NAT type on [this page](https://www.checkmynat.com/). +If you get "Symmetric NAT" result in this test, that means you cannot setup publicly available server with internet connection that you are using. + +Here is more detailed scheme of different NAT types compatibility, it explains are users with different NAT types can connect to each other or not. +Client NAT type on rows, server NAT type on columns: + +| *NAT Type* | Full Cone | Restricted Cone | Port Restricted Cone | Symmetric | +| -------------------- | --------- | --------------- | -------------------- | --------- | +| Full Cone | ✔️ | ✔️ | ✔️ | ✔️ | +| Restricted Cone | ✔️ | ✔️ | ✔️ | ✔️ | +| Port Restricted Cone | ✔️ | ✔️ | ✔️ | ❌ | +| Symmetric | ✔️ | ✔️ | ❌ | ❌ | + +## How to use NAT bypass feature? +If you are starting server within the game, you need to enable option "*Use NAT Bypass instead of direct mode*" in bottom left corner of screen. + +If you are starting dedicated server, you should add console variable `sv_nat 1` to server.cfg file, or add `+sv_nat 1` to server startup parameters. + +If you need to connect to server behind NAT, there is separate tab named *NAT* for such servers in server browser. Note that it is useless to add NAT server to favorites, +or somehow trying manually to store it, because it has changing address and port.