Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/rogual/net.js

Simple networking for HTML games
https://github.com/rogual/net.js

Last synced: 3 days ago
JSON representation

Simple networking for HTML games

Awesome Lists containing this project

README 

        
net.js -- Simple networking for HTML games



Features

    - Modular, extensible client-server RPC system

    - Player management

    - Chat



Still to do

    - Provide library as one standalone file

    - Fast binary protocol



Running the test app



    1. Install dependencies

        npm install



    2. Start lobby

        node lobby.js 8002



    3. Start p2p broker

        (install js-platform/p2p from github and start it)



    4. Start test server

        npm install -g http-server

        http-server -p 8001 -c-1



    5. Run test

        Open localhost:8001/main.html



Adding net.js to your project



    Couple of rough edges here. Net.js is a RequireJS module, and I haven't

    gotten around to compiling a stand-alone version yet, so you'll have to use

    RequireJS to load it.



    

    

    

        require.config({

            // tell RequireJS where net.js is here

        });

        require(['net'], function(net) {

            // Use net here

        });

    



    Ideally we could include p2p-client.js as a dependency, but I haven't

    figured out how to successfully feed it to RequireJS yet.



Tutorial



    Have a read through src/test.js -- it's a heavily commented example game

    designed to serve as a tutorial.



API reference



    net.Lobby(brokerUrl) -> lobby



        The Lobby module communicates with the lobby server (server/lobby.js)

        to implement server discovery.



        lobby.advertise(id, data, cb)



            Tell the lobby about a new game. If id is null, the remote

            lobby will generate one for you.



            If id matches an existing game, this updates that game instead

            of registering a new one.



            Games should be updated once per minute so the server doesn't

            prune them.



            Calls cb(id) when done, with the game's ID.



        lobby.poll(cb) -> cb(err, {date:number, ip:string, data:object}*)



            Returns a list of active games.

                date:  Timestamp of when the game was created, as returned

                       by Date.now()

                ip:    Hosts's IP address

                data:  Custom data given to lobby.advertise()



    net.RPCTable() -> rpcs



        Create and return an RPC table. You'll most likely just want to use

        the RPC table inside your node object at node.rpcTable.



        rpcs.add(fn)



            Add a function to the table. When a remote RPC request is

            received, the function will be called as fn(conn, ...) where

            ... represents the arguments given by the caller, and conn is

            the connection to the caller or null if this is a local call.



        rpcs.call(meta, msg)



            Decode an RPC message and call the appropriate RPC in the table,

            prepending the given meta object to the received arguments.



    net.Node(brokerUrl, role, onReady)



        A node is your local endpoint in the network. It's either a client

        or a server. Each network has one server and any number of clients.



        You will most likely only want to instantiate one Node object in

        your program.



        Most of the functionality in the Node module has to do with managing

        remote procedure calls (RPCs). Higher-level functionality is included

        in the other modules, most of which take a Node as an argument.



        Arguments:



            brokerUrl: URL where p2p host is running. Server is available on

                       github at js-platform/p2p



            role: 'client' or 'server'



            onReady: called with node object when ready.



            route: Name of the underlying route. The broker server assigns

                   a route to the node before onReady is called. Anyone with the

                   route name can connect to this node via the broker.



        Properties common to client and server nodes:



            node.local(rpc, ...)



                Call a named RPC on the local machine.



            node.remote(recipient, rpc, ...)



                Queue up an RPC call to be sent to the given recipient, which

                should be a Peer or Connection object.



            node.server(rpc, ...)



                Arrange for the RPC to be called on the server. If this is

                the local node, call it locally immediately. Otherwise, queue

                it to be sent to the server.



            node.process()



                Send all queued RPCs. This should be called at a regular

                rate. Common update rates for action games are typically

                around 10Hz.



            node.role



                'client' or 'server'.



            node.onstatechange(state)



                Called when connecting as a client, and again when connection is

                successful.



        Properties unique to server nodes:



            node.listen()



                Start listening for client connections.



            node.close()



                Stop listening for client connections.



            node.broadcast(...)



                Call the specified RPC remotely for each remote player, and

                locally for each local player. Note: there can only be one

                local player.



            node.ondisconnect(clientConnection)



                Called when a client disconnects.



        Properties unique to client nodes:



            node.connect(route, cb)



                Connect to the given route. Call cb() on success, or cb(e)

                on error.



            node.close()



                Disconnect.



    net.Players(node, numSlots) -> players



        Adds player management to a node. Instead of just bare connections,

        you get a list of player objects which can have names, scores and

        any other data you like.



        players.login(credentials)



            Called when a client tries to log in. Return an object of

            custom player data on success, or null on failure. The

            default implementation just uses the credentials object

            itself. Reassign this function to customize it.



        players.add(player)



            Add a player and notify all clients. Player objects are

            expected to have these fields:



                connection: Optional remote connection

                data:       Game-specific data



            You'll probably want to use this to add local players, and

            let remote players get added automatically using the login

            system.



        players.remove(player)



            Remove a player and notify all clients.



        players.all



            List of all player slots, Each slot contains either a player

            or null.



        players.forEach(cb)



            Convenience function to iterate over occupied player slots. Calls

            cb(player, id) for each player in the game.



    net.Chat(node) -> chat



        Adds simple chat capabilities to a node.



        chat.onmessage(from, message)



            User-assignable callback. Called when a message is received.

            'from' is the player.data property of the sender.



        chat.send: RPC (s) (message)



            Call to send a message.