From 486b75f9d84412d0f8f518e2ee4398e3bc01c0fa Mon Sep 17 00:00:00 2001
From: vinci6k <makiblade@gmail.com>
Date: Thu, 1 Sep 2022 00:20:08 +0200
Subject: [PATCH] Updated the README file.

---
 README.md                                     | 51 ++++++++++++++++++-
 .../packages/custom/enki/players/entity.py    | 12 ++---
 examples/water_splash/water_splash.py         |  2 +
 examples/water_walk/water_walk.py             |  3 ++
 4 files changed, 61 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index e12905b..513b4aa 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,50 @@
-# enki
\ No newline at end of file
+# Enki 
+This is a small custom package for [Source.Python](https://github.com/Source-Python-Dev-Team/Source.Python) that gives plugin developers quick and easy access to the Player instance whenever the player starts or stops touching water.
+
+<img src="https://i.giphy.com/media/Wayqf54mH2LabBeJlM/giphy.webp" width="412px" /> <img src="https://media0.giphy.com/media/pqWtHQWqZDcbV5cn1C/giphy.gif" width="412px" />  
+*First gif: [water_spash.py](https://github.com/vinci6k/enki/blob/master/examples/water_splash/water_splash.py); Second gif: [water_walk.py](https://github.com/vinci6k/enki/blob/master/examples/water_walk/water_walk.py)*
+
+## Installation
+1. [Install Source.Python](http://wiki.sourcepython.com/general/installation.html).
+2. Download [the latest release](https://github.com/vinci6k/enki/releases) of Enki.
+3. Extract the files into your game server's root folder.<br/>(e.g. ../csgo/ for Counter-Strike: Global Offensive)
+4. Restart your server.
+
+## Usage
+```py
+# ../water_splash/water_splash.py
+
+# Source.Python
+from entities.entity import Entity
+from stringtables import string_tables
+
+# Enki
+from enki.listeners import OnPlayerEnterWater
+
+
+@OnPlayerEnterWater
+def on_player_enter_water(player):
+    """Called when a player starts touching water."""
+    # Did the player enter the water at a reasonable velocity?
+    if player.velocity.length > 300:
+        # Let's make a big water splash!
+        particle = Entity.create('info_particle_system')
+        particle.origin = player.origin
+        # NOTE: This particle effect only exists in CS:GO, there are similar
+        # effects in other games, e.g. 'water_splash_01' in CS:S.
+        particle.effect_name = 'explosion_basic_water'
+        particle.effect_index = string_tables.ParticleEffectNames.add_string(
+            'explosion_basic_water'
+        )
+        particle.start()
+        particle.delay(1, particle.remove)
+```
+There are a few more [examples](https://github.com/vinci6k/enki/tree/master/examples) which showcase how this package works.  
+To see all the available imports/modules, head over to the [wiki](https://github.com/vinci6k/enki/wiki).
+
+
+## Supported Games
+Counter-Strike: Source  
+Counter-Strike: Global Offensive  
+Half Life 2: Deathmatch  
+Team Fortress 2  
diff --git a/addons/source-python/packages/custom/enki/players/entity.py b/addons/source-python/packages/custom/enki/players/entity.py
index 6aaeb1c..82b8134 100644
--- a/addons/source-python/packages/custom/enki/players/entity.py
+++ b/addons/source-python/packages/custom/enki/players/entity.py
@@ -1,8 +1,9 @@
 # ../enki/players/entity.py
 
 # Source.Python
-from engines.trace import (ContentMasks, GameTrace, Ray, TraceFilterSimple, 
-    engine_trace)
+from engines.trace import (
+    ContentMasks, GameTrace, Ray, TraceFilterSimple, engine_trace
+)
 from mathlib import Vector
 from players.entity import Player
 
@@ -17,7 +18,7 @@
 
 class EnkiPlayer(Player):
     """Extended Player class.
-    
+
     Args:
         index (int): A valid player index.
         caching (bool): Check for a cached instance?
@@ -67,10 +68,10 @@ def disable_water_walking(self):
 
         self.walk_on_water = False
         self.rise_think.stop()
-    
+
     def _rise_think(self):
         water_level = self.water_level
-        
+
         # Is the player no longer touching the water?
         if water_level == WaterLevel.NOT_IN_WATER:
             self.rise_think.stop()
@@ -104,4 +105,3 @@ def get_water_trace(self):
             )
 
         return trace
-        
diff --git a/examples/water_splash/water_splash.py b/examples/water_splash/water_splash.py
index a132e85..fffc7bc 100644
--- a/examples/water_splash/water_splash.py
+++ b/examples/water_splash/water_splash.py
@@ -16,6 +16,8 @@ def on_player_enter_water(player):
         # Let's make a big water splash!
         particle = Entity.create('info_particle_system')
         particle.origin = player.origin
+        # NOTE: This particle effect only exists in CS:GO, there are similar
+        # effects in other games, e.g. 'water_splash_01' in CS:S.
         particle.effect_name = 'explosion_basic_water'
         particle.effect_index = string_tables.ParticleEffectNames.add_string(
             'explosion_basic_water'
diff --git a/examples/water_walk/water_walk.py b/examples/water_walk/water_walk.py
index 13b3aba..7c0f4e1 100644
--- a/examples/water_walk/water_walk.py
+++ b/examples/water_walk/water_walk.py
@@ -1,5 +1,8 @@
 # ../water_walk/water_walk.py
 
+# NOTE: This example was made for Counter-Strike: Global Offensive, as it
+# uses the weapon inspect command to trigger the water walking mechanic.
+
 # Source.Python
 from commands import CommandReturn
 from commands.client import ClientCommand