Update README.md

2018-11-02 03:02:10 -04:00 · 2018-11-02 03:02:10 -04:00 · a0e54ebd2f
commit a0e54ebd2f
parent 339c9926e2
1 changed files with 49 additions and 1 deletions
--- a/README.md
+++ b/README.md
@ -1,7 +1,55 @@
-**rage-rpc** simplifies two-way communication between the RAGE Multiplayer server, client, and browser instances by providing a easy-to-use API for calling remote code and retrieving results.
+## Motivation
+
+A very common workflow when developing with any kind of client-server platform is not only sending data between the server and clients, but also receiving data back after performing some kind of action. An example would be a client asking for information from a database in order to display to the user. One technique to achieve this is called [remote procedure calls (RPC)](https://en.wikipedia.org/wiki/Remote_procedure_call) which allows one application context to call code in a completely separate context and return the result back to the caller, as if it were local to begin with.
+
+In RAGE Multiplayer, this kind of functionality is not supported natively. In order for a player to ask something of the server, the server must set up an event handler that the player calls remotely, then the server does its processing and calls _another_ event handler that resides on the client. There are many pitfalls to this approach, including but not limited to messy code and false identification (am i sending the response to the right caller instance?). Natively, the server cannot directly communicate with CEF instances at all. You have to route *all requests* through the client. Suddenly, you have 16 different events to handle one simple data request. It's horrible. And when your codebase starts growing, it becomes a huge hassle to deal with.
+
+This is pretty much what everybody has learned to deal with, until now. `rage-rpc` simplifies two-way communication between the RAGE Multiplayer server, client, and browser instances by providing a easy-to-use API for calling remote code and retrieving results. **Any context can call a function that resides in any other context and immediately get access to its return value without messing with events.** This means any CEF instance can call code on the server, the client, or any other CEF instances and easily see the result.

 ---

+## Installation
+
+#### Option 1
+
+You can install via [npm](https://github.com/npm/cli)
+
+```
+npm i -S rage-rpc
+```
+
+From here, you can simply require the package in any RAGE context:
+
+```javascript
+const rpc = require('rage-rpc');
+```
+
+#### Option 2
+
+In the `dist/` folder of this repository is a single minified JS file that you can download and require into any RAGE context. It works the same as the above option, but you'll have to manually redownload the file when new versions are released.
+
+```javascript
+const rpc = require('./rage-rpc.min.js');
+```
+
+#### Option 3 (Browser Only)
+
+In order to use `require` in the browser, you'll need either an AMD loader or some kind of bundler like Webpack. If those options don't suit your project, you can load the file into browser contexts with just a script tag before the code you use it in. It will expose a global `rpc` variable that you can use on your page.
+
+```html
+<html>
+    <head>
+        <title>My CEF Page</title>
+        <script type="text/javascript" src="./rage-rpc.min.js"></script>
+        <script type="text/javascript">
+            rpc.register('hi', () => 'hello from cef!');
+            
+            // ...
+        </script>
+    </head>
+</html>
+```
+
 ## Examples

 ### Server to Client