Merge pull request #691 from swimos/ripple

Ripple example application

Author: SirCipher

Cargo.toml

@@ -40,7 +40,7 @@ members = [
     "example_apps/join_value",
     "example_apps/aggregations",
     "example_apps/time_series",
-    "example_apps/devguide",
+    "example_apps/devguide", "example_apps/ripple",
 ]
 
 [workspace.package]

README.md

@@ -22,12 +22,15 @@ host can share a single web-socket connection.
 [![SwimOS Form Crates.io Version][swimos-form-badge]][swimos-form-crate]
 
 [swimos-badge]: https://img.shields.io/crates/v/swimos?label=swimos
+
 [swimos-crate]: https://crates.io/crates/swimos
 
 [swimos-form-badge]: https://img.shields.io/crates/v/swimos?label=swimos_form
+
 [swimos-form-crate]: https://crates.io/crates/swimos_form
 
 [swimos-client-badge]: https://img.shields.io/crates/v/swimos?label=swimos_client
+
 [swimos-client-crate]: https://crates.io/crates/swimos_client
 
 [Website](https://swimos.org/) | [Developer Guide](https://www.swimos.org/server/rust/developer-guide/) | [Server API Docs](https://docs.rs/swimos/latest/swimos/) | [Client API Docs](https://docs.rs/swimos_client/latest/swimos_client/)
@@ -123,6 +126,9 @@ lane will then be set to `5` and the following will be printed on the console:
 Received value: 5 for 'lane' on agent at URI: /examples/name.
 ```
 
+A number of example applications are available in the [example_apps](example_apps) directory which demonstrate
+individual features as well as more comprehensive applications.
+
 ## Development
 
 See the [development guide](DEVELOPMENT.md).

example_apps/README.md

@@ -19,6 +19,7 @@ binaries for their corresponding client applications. Each directory contains de
 - [map_lane_persistence](map_lane_persistence): Application demonstrating Map Lanes with persistence.
 - [map_store](map_store): Application demonstrating Map Stores.
 - [map_store_persistence](map_store_persistence): Application demonstrating Map Stores with persistence.
+- [ripple](ripple): Real-time synchronous shared multiplayer experience.
 - [supply_lane](supply_lane): Application demonstrating Supply Lanes.
 - [time_series](time_series): Reference code for the [Time Series](https://www.swimos.org/server/rust/time-series/)
   guide.

example_apps/ripple/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "ripple"
+version.workspace = true
+authors.workspace = true
+edition.workspace = true
+license.workspace = true
+homepage.workspace = true
+publish = false
+
+[dependencies]
+swimos = { workspace = true, features = ["server", "agent"] }
+swimos_form = { workspace = true }
+example-util = { path = "../example_util" }
+swimos_utilities = { workspace = true, features = ["trigger"] }
+axum = { workspace = true, features = ["tokio", "http1"] }
+tracing = { workspace = true }
+tracing-subscriber = { workspace = true, features = ["env-filter"] }
+futures = { workspace = true }
+tokio = { workspace = true, features = ["rt-multi-thread", "macros", "sync", "io-util", "fs"] }
+tokio-util = { workspace = true }
+rand = { workspace = true }
+chrono = { workspace = true }

example_apps/ripple/README.md

@@ -0,0 +1,30 @@
+# Ripple
+
+![Ripple](assets/ripple.png "Ripple")
+
+Ripple is a real-time synchronous shared multiplayer experience built on the Swim platform.
+
+See a hosted version of this app [here](https://ripple.swim.inc).
+
+## Usage
+
+Run the application using:
+
+```shell
+$ cargo run --bin ripple
+```
+
+Internally, this will spawn two servers: the Swim server which is running at localhost:9001 and a UI server running
+at http://localhost:9002. Using your browser, navigate to http://localhost:9002/index.html and randomly click
+on the screen to generate 'ripples'. These ripples are propagated to all users which are connected to the Swim server.
+You may also hold your mouse's left button down to generate a 'charge' which is denoted by a larger circle displayed on
+the screen.
+
+This example application demonstrates a number of core Swim features:
+
+- Value Lanes: To propagate the latest ripple.
+- Map Lanes: To propagate the current charges that are happening.
+- Command Lanes: For publishing new ripples and charges.
+- Custom Event Types: Structures and Enumerations are used by Command Lanes for mutating the state of lanes.
+- Event Handlers: Event Handlers are scheduled to run at random intervals to generate new ripples and prune any old
+  charges that were not automatically removed if a user's browser suddenly closed.