From a694c2a654c99f3ed95d556140a25423621d24b1 Mon Sep 17 00:00:00 2001 From: Paco Hope Date: Mon, 15 Aug 2022 09:05:18 -0400 Subject: [PATCH] Added new pages and linked in --- docs/source/syntax.rst | 120 +++++++++++++++++++++++++++++++++++++++++ docs/source/yaml.rst | 30 +++++++++++ 2 files changed, 150 insertions(+) create mode 100644 docs/source/syntax.rst create mode 100644 docs/source/yaml.rst diff --git a/docs/source/syntax.rst b/docs/source/syntax.rst new file mode 100644 index 0000000..da54523 --- /dev/null +++ b/docs/source/syntax.rst @@ -0,0 +1,120 @@ +.. _syntax-page: + +=================== +TFScript Syntax +=================== + +A TFScript file is structured like this + +.. code-block:: + :caption: Basic tfscript input file + + class1: + key1: + type: + fields + key2: + type: + fields + ... + + class2: + key1: + ... + +where ``class1``, ``class2``, etc. refer to classes such as soldier, pyro, or any of the other lovable mercenaries. + +``key1`` and ``key2`` are keys such as ``w`` or ``mouse1`` to which you want actions bound, and ``type``/``fields`` is the data to be parsed by TFScript to generate a config file. + +.. _syntax-classes: + +Classes +============== + +The full list of valid class names is as follows: + +* Scout +* Soldier +* Pyro +* Demo +* Heavy +* Engi +* Medic +* Sniper +* Spy +* Default + +As you may have noticed, there is a special class, "default", which specifies the default state of any and all keys. Any keybinds in this config are the defaults, and apply to all other classes unless specifically overwritten (that said, any classes which *do* have a different definition for that key will overwrite the previous "default" definition). + +Names are not case sensitive, so "SoLDiER" will work just as well as "soldier". + +.. _syntax-keys: + +Keys +================ + +If you are already familiar with TF2 scripting, every key that tf2 recognizes is also recognized by TFScript. + +For the rest of us, the most relavent keys are: + +* A to Z +* 0 to 9 +* space +* tab +* capslock +* shift +* ctrl +* function +* alt + +For the remaining symbol characters (like "\`", "[", or "\\"), just press the key that it appears on, on your keyboard. *Do not* hold shift, alt, or any other control keys. This does limit the keys you can use, for example if you wanted to use the \{ character, you would be stuck with \[. This is a limit imposed by TF2, but you can get around this using the ``double`` type, as explained later. + +.. _syntax-examples: + +Some examples +================== + +For example, this config will bind "e" to call for medic, unless mouse4 is held, in which case it will call for an ÜberCharge: + +.. code-block:: + :caption: Example tfscript for binding ubercharge: + + alias call_for_medic "voicemenu 0 0" + alias call_for_uber "voicemenu 1 6" + alias e_bind call_for_medic + bind e e_bind + alias +toggle_state "alias e_bind call_for_uber" + alias -toggle_state "alias e_bind call_for_medic" + bind mouse4 "+toggle_state" + +There are some issues with this: + +* It is quite verbose, and if several of these exist the file can become difficult to traverse +* There is a lack of clarity in the voicemenu command, only the bind name explains what it does +* If either "mouse4" or "e" had a prior function, it has now been overwritten +* The scope is dictated by what ``.cfg`` file this is located within, which can cause problems + + +The TFScript way of doing this is: + +.. code-block:: + :caption: Basic tfscript input file + + default: + e: + double: + primary: + impulse: voice medic + secondary: + impulse: voice activate uber + condition: mouse4 + +There are several benefits to this: + +* The indentation allows for easier scanning of the file +* The voicemenu commands have been replaced with the clearer "voice" impulse +* Since this is within the ``default`` section, it is clear that there are is no "prior function" to overwrite and this will apply to all classes unless specifically overwritten. + +.. meta:: + :description: TFScript scripting tool for Team Fortress 2 + :keywords: Team Fortress, TF2, tf2 script diff --git a/docs/source/yaml.rst b/docs/source/yaml.rst new file mode 100644 index 0000000..026cb07 --- /dev/null +++ b/docs/source/yaml.rst @@ -0,0 +1,30 @@ +.. _yaml-page: + +=================== +YAML Syntax +=================== + +TFScript uses YAML to express how you want your keybindings to work. YAML is a `well known data format `_ that helps you write structured data in a plain text file. That means you write out a hierarchy of things, with the attributes of those things, and program like ``tfscript`` can read that data file in very carefully and use it to do what you wanted. In this case, we define a YAML format for TF2 scripting. You can write terse little blocks of YAML that expand into multiple lines of TF2 script, including standard checks for server-side features and common mistakes. + +Example +============= + +.. code-block:: + :caption: Basic tfscript input file + + class1: + key1: + type: + fields + key2: + type: + fields + ... + + class2: + key1: + ... + +.. meta:: + :description: TFScript scripting tool for Team Fortress 2 + :keywords: Team Fortress, TF2, tf2 script