Documentation update

COMMON-MISTAKES.md

@@ -1,14 +1,39 @@
-**Originally from a pinned nxrighthere repo issue:**
+## Common Mistakes working with ENet-CSharp
 
-Since newcomers make the same mistakes over and over again, and people are reading the API reference not careful enough, I will collect all common mistakes here.
-1. **Packet.Dispose() called right after sending a packet.** Never dispose a packet after enqueuing it for sending, ENet does that for you automatically, otherwise, a memory access failure will occur.
+This file describes some mistakes that newcomers or even experienced veterans can make. Here's some that have been collected over time.
 
-2. **Packet.Dispose() called more than once per received packet.** The Packet structure is a value type thus internal checks will fail for two different copies of a packet, and a memory access failure will occur. Try to keep processing flow under strict control. If the received packet will be sent further, you should not dispose it since ENet will use it as you normally enqueuing a packet for sending.
+### `Packet.Dispose()` called right after sending a packet.
 
-3. **Channels limit didn't match at the endpoints.** Always make sure that the channel limit set to the same value at the endpoints using Host.Create() and Host.Connect() functions, otherwise, packets will not be delivered on disabled channels.
+Never dispose a packet after enqueuing it for sending, ENet does that for you automatically, otherwise, a memory access failure will occur.
 
-4. **Round-trip time is unstable even on localhost.** This is the first indication that the Host.Service() is not called often enough. Make sure that the service and events are processed continuously and nothing prevents the ENet to shuttle packets across peers.
+### `Packet.Dispose()` called more than once per received packet.
 
-5. **Latency gets higher relatively to a count of concurrent connections.** Make sure that only the actual payload is sent and not a whole buffer, a packet should be created with the correct length using the Packet.Create() function. Check that the ENet is not overwhelmed with large reliably fragmented packets.
+The `Packet` structure is a value type thus internal checks will fail for two different copies of a packet, and a memory access failure will occur. Try to keep processing flow under strict control. If the received packet will be sent further, you should not dispose it since ENet will use it as you normally enqueuing a packet for sending.
 
-6. **The host is not flushed after the service is no longer in a loop.** Always flush the host before the end of a session to ensure that all queued packets and protocol commands were sent to its designated peers.
+### Channels limit didn't match at the endpoints.
+
+Always make sure that the channel limit set to the same value at the endpoints using `Host.Create()` and `Host.Connect()` functions. Failure to do so otherwise results in packets will not be delivered on disabled channels.
+
+### Round-trip time is unstable even on localhost.
+
+This is the first indication that the `Host.Service()` is not called often enough. Make sure that the service and events are processed continuously and nothing prevents the ENet to shuttle packets across peers.
+
+### Latency gets higher relatively to a count of concurrent connections.
+
+Make sure that only the actual payload is sent and not a whole buffer, a packet should be created with the correct length using the `Packet.Create()` function. Check that the ENet is not overwhelmed with large [reliably fragmented](https://github.com/SoftwareGuy/ENet-CSharp/DOCUMENTATION.md#packetflags) packets.
+
+### A host is unable to accept multiple connections or degrades with many packets.
+
+Make sure that the service is processing as many events as possible and not only one event per frame/iteration. Put the service into a loop even within a game loop (but without a timeout to avoid blocking). Utilizing C# Threads can help too.
+
+If nothing helps, you can try to increase the socket buffer size of the host up to one megabyte using the appropriate parameter at both ends.
+
+### A host is not flushed after the service is no longer in a loop.
+
+Always flush the host before the end of a session to ensure that all queued packets and protocol commands were sent to its designated peers.
+
+### Unreliable packets are dropped significantly under simulation of latency.
+
+If the simulated delay/ping is applied in the middle of the process, but not before connection establishment, then unreliable packets will be throttled if simulated latency exceeds the threshold (20 ms by default between service updates). See the description of `Peer.ConfigureThrottle()` [here](https://github.com/SoftwareGuy/ENet-CSharp/DOCUMENTATION.md) for details and parameters tuning.
+
+This document will be updated as time goes on.

README.md

@@ -8,47 +8,64 @@
 
 _**Please consider a donation (see the Ko-Fi button above) if this project is useful to you.**_
 
+## What's this?
+This is a improved/refactored version of ENet-CSharp, forked from another ENet fork. Due to unfortunate circumstances between two development entities, the upstream repository was archived and is only updated when patches are applied (all development work is done in private). Since you cannot interact with archived repositories outside of code-related things, this repository acts as a workaround to those issues.
 
-This is a improved/refactored version of ENet-CSharp. Due to unfortunate circumstances between two development entities, the upstream repository was archived and is only updated when patches are applied (all development work is done in private). Since you cannot interact with archived repositories outside of code-related things, this repository acts as a workaround to those issues.
+In short, this is an independent ENet implementation with a modified protocol for C, C++, C#, and other languages. The original C library both forks are based on can be found [here](https://github.com/lsalzman/enet).
 
 Unlike the upstream repository code of conduct where issue tickets were closed randomly for no reason, if you have a problem with ENet-CSharp, we'll be able to investigate. We also have a proper implementation of the `ENET_DEBUG` definition, allowing logging output to be written to `enet_log.txt` for further diagnosis and troubleshooting. Code cleanups and optimizations for better performance are included, and if someone files a supposedly-a-bug tickets actually get analyzed and if it's really a bug, it'll get fixed.
 
-### Compatibility with Upstream
+## Compatibility with Upstream
 Don't use the upstream releases with the code in this repository. You will most likely get crashes or weird things happening.
 
-### Building
+## Building
 You can use the IDE of Visual Studio to build if you like. The following will be oriented for power users and command line heroes.
 
-Unlike upstream, this repo has a complete build system that harnesses the power of `MSBuild`. 
+Unlike upstream, this repo has a complete build system that harnesses the power of `MSBuild`. Ensure you have a Dotnet SDK at least installed.
 
-- Ensure you have a Dotnet SDK at least installed.
-- **If you are building on Windows:** Make sure you have Visual Studio 2017/2019 installed, C++ Support, Windows 10 SDK and CMake. CMake sometimes doesn't get automatically installed with Visual Studio, so you may need to grab it manually. Ensure it's a recent version.
-- **If you are building on Mac OS:** Make sure you have Xcode CLI Tools installed (XCode might also be required).
-- **If you are building on Linux:** Make sure you have your repositories' `build-essential` and `cmake` package installed. On Debian and Ubuntu-based distros, you can do `sudo apt -y build-essential cmake` to install the required things.
-- **If you are building for Android:** Easiest way is to go into `Sources/Native` and run when `ndk-build`. A fresh batch of ENET DLLs should then be spat out.
-- **If you are building for iOS:** Using **Terminal.app** on your MacOS device, navigate to the `Build-iOS` directory and run the command file found inside. You might need to make it executable, however. It will try to auto-pilot a build for you, just make sure you have CMake installed for MacOS and a recent Xcode installation. Library code signing will be disabled for the build.
-- **If you are building for Consoles:** Unfortunately, I don't have any instructions here. Please let me know how you go and I'll add some here.
+### Desktop Compile
 
-#### Recipe for victory
+- **Windows:** Make sure you have Visual Studio 2017/2019 installed with the C++ Support bundle ticked, a recent Windows 10 SDK and CMake. CMake sometimes doesn't get automatically installed with Visual Studio, so you may need to grab it manually from Kitware's website. Ensure it's a recent version (anything 3.16+ works).
+
+- **MacOS:** Make sure you have Apple Xcode CLI Tools installed (Xcode might also be required for the MacOS SDK).
+
+- **Linux:** Make sure you have your repositories' `build-essential` and `cmake` package installed. On Debian and Ubuntu-based distros, you can do `sudo apt -y build-essential cmake` to install the required things.
+
+### Mobile 
+
+- **Android:** Ensure you have the Android NDK installed. Easiest way to do this to go into `Sources/Native` and run when `ndk-build`. A fresh batch of ENET binaries should then be spat out, which can be used in your project.
+
+- **Apple iOS:** Using **Terminal.app** on your MacOS device, navigate to the `Build-iOS` directory and run the command file found inside. You might need to make it executable, however. It will try to auto-pilot a build for you, just make sure you have CMake installed for MacOS and a recent Xcode installation. Library code signing will be disabled for the build.
+
+### Console
+- **Nintendo Switch:** A old guide is available [here](). However, it will require some modification to work with the Switch OS and Nintendo's own SDK. Since said SDK is under NDA, limited public info can be provided.
+
+- **Playstation 4/Vita:** An Enet Vita port exists already, however I am not planning to add support for the Vita to this repository. PS4 is a question mark.
+
+- **Other console not listed:** Open a issue ticket and I'll gladly add your steps for your platform here.
+
+### Recipe for victory
 - Clone a fresh copy of this Git Repo somewhere on your workstation's filesystem.
 - Open a command prompt/terminal and change directory into the newly cloned git repository.
-- Run `dotnet build`. **Protip:** You can append `-c Release` or `-c Debug` to your `dotnet build` command to build a release binary or a debug binary of ENET's C library. At the moment, the default build is a Debug build.
+- Run `dotnet build`. 
+
+**Protip:** You can append `-c Release` or `-c Debug` to your `dotnet build` command to build a release binary or a debug binary of ENET's C library. At the moment, the default build is a Debug build.
 
-You will see an anime babe appear followed by [Ignorance](https://github.com/SoftwareGuy/Ignorance) ASCII art. 
+You will see an anime babe appear followed by [Ignorance](https://github.com/SoftwareGuy/Ignorance) ASCII art. Thanks to c6 for that eyecandy!
 
 CMake will fire up, configure itself after inspecting your build environment and hopefully spit out a binary blob inside a `Unity/Plugins` directory. On Windows, this will be a DLL, on Mac it will be a `.bundle` file and on Linux it will be a shared object (`.so`). This can be used with Unity or other applications like a C# NET Core application or C/C++ app.
 
-#### Testing
+## Testing
 - `dotnet test` will run some sanity checks and make sure ENET initializes, data is received and sent correctly, etc.
 
-#### Rebuilding
+## Rebuilding
 Inside the directory that you cloned the repo to, run:
 - `dotnet clean`
 - `dotnet build` (don't forget about the `-c Release/Debug` argument as mentioned earlier!)
 
 It is recommended to clean the repository work space before building.
 
-### Features
+## Native Library Features
 - Lightweight and straightforward
 - Low resource consumption
 - Dual-stack IPv4/IPv6 support
@@ -56,40 +73,39 @@ It is recommended to clean the repository work space before building.
 - Aggregation
 - Adaptability and portability
 
-### Usage
+## Usage
 - Initialize ENET first before doing anything by calling the `ENet.Library.Initialize();` function. It will return false on failure, return true on success. You can use this to gracefully quit your application should it fail to initialize, for example.
 - Once you are done, deinitialize the library using `ENet.Library.Deinitialize();` function.
 
-### Code Examples/Quick Start
-A good idea is to check out the [common mistakes during integration](https://github.com/SoftwareGuy/ENet-CSharp/blob/master/COMMON-MISTAKES.md) documentation.
-
-Looking for example code and gotta go fast? No problem, got you [covered here](https://github.com/SoftwareGuy/ENet-CSharp/blob/master/QUICKSTART-EXAMPLES.md).
+### ENet-CSharp with Unity
+Usage is almost the same as in the .NET environment, except that the console functions must be replaced with functions provided by Unity. If the `Host.Service()` will be called in a game loop, then make sure that the timeout parameter set to 0 which means non-blocking. Also make sure Unity runs in the background by enabling the ***Run in Background*** player setting.
 
-### Unity
-Usage is almost the same as in the .NET environment, except that the console functions must be replaced with functions provided by Unity. If the `Host.Service()` will be called in a game loop, then make sure that the timeout parameter set to 0 which means non-blocking. Also, make sure Unity runs in the background by enabling the ***Run in Background*** player setting.
+### Code Examples/Quick Start
+A good idea is to check out the [common mistakes during integration](https://github.com/SoftwareGuy/ENet-CSharp/blob/master/COMMON-MISTAKES.md) documentation. Looking for example code and gotta go fast? No problem, got you [covered here](https://github.com/SoftwareGuy/ENet-CSharp/blob/master/QUICKSTART-EXAMPLES.md).
 
-Multi-threading
---------
+## Multi-threading
 ### Strategy
-The best-known strategy is to use ENet in an independent I/O thread. This can be achieved by using Threads and enqueuing packets to be sent and received back and forth via ConcurrentQueues (this is what [Ignorance](https://github.com/SoftwareGuy/Ignorance) uses). In fact, some internal testing showed that ENet had very impressive performance using a thread and ConcurrentQueues approach to network I/O, even faster than RingBuffers/Disruptors. Use whatever queue system you feel comfortable with, just make sure you empty the queues as fast as possible in your applications.
+The best-known strategy is to use ENet in an independent I/O thread. This can be achieved by using Threads and enqueuing packets to be sent and received back and forth via ConcurrentQueues, for example. RingBuffers and Disruptors are also solid performance options too. Use whatever queue system you feel comfortable with, just make sure you empty the queues as fast as possible in your applications.
 
-Threading in Unity was problematic but later versions (2018.3+) have proven to be fine. 
-Please beware that using Threads inside a Unity environment can be problematic and can lead to the Unity Editor or built games randomly crashing without any warning. Use them with caution!
+A real world example is Oiran Studio's [Ignorance](https://github.com/SoftwareGuy/Ignorance) transport which uses this ENET-CSharp fork via a Threaded Implementation to ensure the network threads run as fast as ENET can pump.
 
-### Functionality
+### Unity Warning
+Threading in Unity was problematic but later versions (2018.3+) have proven to be fine. Please beware that using Threads inside a Unity environment can be problematic and can lead to the Unity Editor or built games randomly crashing without any warning. Use them with caution!
+
+### Thread Safety
 In general, ENet is not thread-safe, but some of its functions can be used safely if the user is careful enough:
 
-`Packet` structure and its functions are safe until a packet is only moving across threads by value and a custom memory allocator is not used.
+- The `Packet` structure and its functions are safe until a packet is only moving across threads by value and a custom memory allocator is not used.
 
-`Peer.ID` as soon as a pointer to a peer was obtained from the native side, the ID will be cached in `Peer` structure for further actions with objects that assigned to that ID. `Peer` structure can be moved across threads by value, but its functions are not thread-safe because data in memory may change by the servicing functions in another thread.
+- `Peer.ID`: As soon as a pointer to a peer was obtained from the native side, the ID will be cached in the `Peer` structure for further actions with objects that assigned to that ID. The `Peer` structure can be moved across threads by value, but its functions are not thread-safe because data in memory may change by the servicing functions in another thread.
 
-`Library.Time` utilizes atomic primitives internally for managing local monotonic time.
+- `Library.Time`: utilizes atomic primitives internally for managing local monotonic time.
 
-API Documentation
+### API Documentation
 --------
 See `DOCUMENTATION.md` [here](https://github.com/SoftwareGuy/ENet-CSharp/blob/master/DOCUMENTATION.md).
 
-Supporters
+### Supporters
 --------
 This fork is used by and supported by [Oiran Studio](http://www.oiran.studio).
 
@@ -97,13 +113,14 @@ This fork is used by and supported by [Oiran Studio](http://www.oiran.studio).
   <img src="http://www.oiran.studio/OiranFanFinal_Colour_Mini.png" alt="Oiran Studio Logo">
 </p>
 
-Credits
--------
+### Credits
+
 - Coburn
 - c6burns
 - Katori
 - Mirror Team & Discord Members
 
-Some thanks to:
+#### Some thanks to:
 - Vincenzo from Flying Squirrel Entertainment
-- nxrighthere
+- lsalzman for the original enet repository
+- nxrighthere