doc: Add READMEs (#74)

Closes #67

README.md

@@ -0,0 +1,90 @@
+<p style="text-align: center">
+  <img src="docs/assets/netfox.svg" />
+</p>
+
+# netfox
+
+A set of addons for responsive online games with the [Godot engine].
+
+## Features
+
+* ⏲️  Consistent timing across multiple machines
+* 🖥️ Supports client-server architecture
+* 🧈 Smooth motion with easy-to-use interpolation
+* 💨 Lag compensation with Client-side Prediction and Server-side Reconciliation
+* 🛜 Bullet-proof connectivity with [noray] integration
+
+## Overview
+
+The package consists of multiple addons, each with different features:
+
+* [netfox]
+  * The core package, implements timing, rollback and other multiplayer
+    features
+  * *Start here*
+* [netfox.noray]
+  * Implements [noray] integration to establish connection between players
+  * *Useful for online games*
+* [netfox.extras]
+  * Provides high-level, game-specific, convenience features built on top of
+    netfox, like base classes for input management or weapons
+  * *Check for reusable components for your game*
+
+## Install
+
+### Source
+
+Download the [source] and copy the addons of your choice to your Godot project.
+
+### Asset Library
+
+TBA
+
+## Usage
+
+See the docs ( TBA ).
+
+### Examples
+
+#### Comparison sample
+
+* [Single player](examples/single-player)
+* [Simple example](examples/multiplayer-simple)
+* [Example with netfox](examples/multiplayer-netfox)
+
+To provide a short intro on how to get started with netfox, and how it fares
+compared to built-in multiplayer tools, a simple demo was implemented as a
+single-player game, which was ported to multiplayer using both a naive approach
+and netfox.
+
+#### Example game
+
+* [Forest Brawl]
+
+To provide examples of netfox usage in an actual game, [Forest Brawl] was
+created and included specifically for this purpose.
+
+It's a party game where an arbitrary amount of players compete by trying to
+knock eachother off of the map.
+
+## License
+
+netfox is under the [MIT license](LICENSE).
+
+Note that the repository contains assets made by other people as well. For
+these cases, the relevant licenses can be found in the assets' directories.
+
+## Issues
+
+In case of any issues, comments, or questions, please feel free to [open an issue]!
+
+[source]: https://github.com/foxssake/netfox/archive/refs/heads/main.zip
+[Godot engine]: https://godotengine.org/
+[noray]: https://github.com/foxssake/noray
+
+[netfox]: addons/netfox
+[netfox.noray]: addons/netfox.noray
+[netfox.extras]: addons/netfox.extras
+[Forest Brawl]: examples/forest-brawl
+
+[open an issue]: https://github.com/foxssake/netfox/issues

addons/netfox.extras/LICENSE

@@ -0,0 +1,18 @@
+Copyright 2023 Gálffy Tamás
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

addons/netfox.extras/README.md

@@ -0,0 +1,39 @@
+# netfox.extras
+
+High-level, game-specific extras for [netfox]!
+
+## Features
+
+* 🔫 Networked weapons
+* ⌨️  Rollback-aware base class for input
+
+## Overview
+
+This addon is pretty much a catch-all project for things that are useful, but
+are not core to netfox.
+
+## Install
+
+### Source
+
+Download the [source] and copy the netfox.extras addon to your Godot project.
+
+### Asset Library
+
+TBA
+
+## Usage
+
+See the docs ( TBA ).
+
+## License
+
+netfox.extras is under the [MIT license](LICENSE).
+
+## Issues
+
+In case of any issues, comments, or questions, please feel free to [open an issue]!
+
+[netfox]: https://github.com/foxssake/netfox
+[source]: https://github.com/foxssake/netfox/archive/refs/heads/main.zip
+

addons/netfox.extras/plugin.cfg

@@ -3,5 +3,5 @@
 name="netfox.extras"
 description="Game-specific utilities for Netfox"
 author="Tamas Galffy"
-version="0.15.0"
+version="0.15.1"
 script="netfox-extras.gd"

addons/netfox.noray/LICENSE

@@ -0,0 +1,18 @@
+Copyright 2023 Gálffy Tamás
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

addons/netfox.noray/README.md

@@ -0,0 +1,170 @@
+# netfox.noray
+
+Bulletproof your connectivity with [netfox]'s [noray] integration!
+
+## Features
+
+* 🤝 Establish connectivity using NAT punchthrough
+  * Uses [noray] for orchestration
+  * Implements a full UDP handshake
+* 🛜 Use [noray] as a relay
+  * Useful in cases where NAT punchthrough fails
+  * If you can see this repo, you probably can connect through [noray]
+
+## Install
+
+### Source
+
+Download the [source] and copy the netfox.noray addon to your Godot project.
+
+> Note: this addon depends on netfox, make sure to include it as well in your project.
+
+### Asset Library
+
+TBA
+
+## Usage
+
+See the docs ( TBA ).
+
+For a full example, see [noray-bootstrapper.gd].
+
+### Setup
+
+All players must connect to noray and register:
+
+```gdscript
+var host = "some.noray.host"
+var port = 8890
+var err = OK
+
+# Connect to noray
+err = await Noray.connect_to_host(host, port)
+if err != OK:
+  return err # Failed to connect
+
+# Register host
+Noray.register_host()
+await Noray.on_pid
+
+# Register remote address
+# This is where noray will direct traffic
+err = await Noray.register_remote()
+if err != OK:
+  return err # Failed to register
+```
+
+Once this process is done, noray has assigned two ID's to the player: an OpenID
+and a PrivateID. The OpenID is used to identify the player, e.g. when others
+want to connect, and is freely shareable. The PrivateID is used by the client
+to identify itself towards noray, and should not be shared.
+
+### Starting a host
+
+To start hosting, use noray's registered local port:
+
+```gdscript
+var peer = ENetMultiplayerPeer.new()
+var err = peer.create_server(Noray.local_port)
+
+if err != OK:
+  return false # Failed to listen on port
+```
+
+### Starting a client
+
+To connect to someone using noray, the target player's OpenID is needed. Note
+that noray itself does not provide any facilities to share these.
+
+For testing, simply displaying the OID for the player and sharing it over
+messaging apps can work as a temporary solution.
+
+```gdscript
+var oid = "abcd1234"
+
+# Connect using NAT punchthrough
+Noray.connect_nat(oid)
+
+# Or connect using relay
+Noray.connect_relay(oid)
+```
+
+The above two calls will return instantly, since they only send a request to
+noray. The actual connection will be orchestrated by noray, and games must
+implement the related callbacks.
+
+### Implementing callbacks
+
+When noray receives a connection request ( either over NAT or relay ), it will
+ask both participants to do a handshake. Once this handshake is successful,
+players may connect to eachother.
+
+This is why callbacks must be implemented.
+
+Client example:
+
+```gdscript
+func _ready():
+  Noray.on_connect_nat.connect(_handle_connect)
+  Noray.on_connect_relay.connect(_handle_connect)
+
+func _handle_connect(address: String, port: int) -> Error:
+  # Do a handshake
+  var udp = PacketPeerUDP.new()
+  udp.bind(Noray.local_port)
+  udp.set_dest_address(address, port)
+
+  var err = await PacketHandshake.over_packet_peer(udp)
+  udp.close()
+
+  if err != OK:
+    return err
+
+  # Connect to host
+  var peer = ENetMultiplayerPeer.new()
+  err = peer.create_client(address, port, 0, 0, 0, Noray.local_port)
+
+  if err != OK:
+    return err
+
+  return OK
+```
+
+> *Note:* Make sure to **always** specifiy the local port for the client - this
+> is the only port noray recognizes, and failing to specify it will result in
+> broken connectivity.
+
+Host example:
+
+```gdscript
+func _ready():
+  Noray.on_connect_nat.connect(_handle_connect)
+  Noray.on_connect_relay.connect(_handle_connect)
+
+func _handle_connect(address: String, port: int) -> Error:
+  var peer = get_tree().get_multiplayer().multiplayer_peer as ENetMultiplayerPeer
+  var err = await PacketHandshake.over_enet(peer.host, address, port)
+
+  if err != OK:
+    return err
+
+  return OK
+```
+
+> *Note:* The host handshake is a bit different, as it can't receive manual
+> packets, only send them. So it assumes that the target is always responsive,
+> and just blasts them with a bunch of packets. If the target is indeed
+> responsive, it can connect. If not, nothing happens, as expected.
+
+## License
+
+netfox.noray is under the [MIT license](LICENSE).
+
+## Issues
+
+In case of any issues, comments, or questions, please feel free to [open an issue]!
+
+[netfox]: https://github.com/foxssake/netfox
+[source]: https://github.com/foxssake/netfox/archive/refs/heads/main.zip
+[noray]: https://github.com/foxssake/noray
+[noray-bootstrapper.gd]: ../../examples/shared/scripts/noray-bootstrapper.gd

addons/netfox.noray/plugin.cfg

@@ -3,5 +3,5 @@
 name="netfox.noray"
 description="Bulletproof your connectivity with noray integration for netfox"
 author="Tamas Galffy"
-version="0.15.0"
+version="0.15.1"
 script="netfox-noray.gd"

addons/netfox/LICENSE

@@ -0,0 +1,18 @@
+Copyright 2023 Gálffy Tamás
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.