@unitn-asa/deliveroo-js-sdk 1.2.1

package/src/server/DjsServerSocket.js

@@ -0,0 +1,316 @@
+import { Socket } from 'socket.io';
+
+/**
+ * @typedef {import("../types/IOAgent.js").IOAgent} IOAgent
+ * @typedef {import("../types/IOParcel.js").IOParcel} IOParcel
+ * @typedef {import("../types/IOTile.js").IOTile} IOTile
+ * @typedef {import("../types/IOConfig.js").IOConfig} IOConfig
+ * @typedef {import("../types/IOInfo.js").IOInfo} IOInfo
+ * 
+ * @typedef {import("../types/IOSocketEvents.js").IOSensing} IOSensing
+ * @typedef {import("../types/IOSocketEvents.js").IOClientEvents} IOClientEvents on the client side these are to be emitted with .emit
+ * @typedef {import("../types/IOSocketEvents.js").IOServerEvents} IOServerEvents on the client side these are to be listened with .on
+ */
+
+
+
+/**
+ * @class
+ * @extends { Socket<IOClientEvents, IOServerEvents> }
+ */
+export class DjsServerSocket extends Socket {
+
+    warnings = new Array();
+
+    // /**
+    //  * @template {keyof IOClientEvents} K
+    //  * @param {K} event
+    //  * @param {IOClientEvents[K]} listener
+    //  * @returns {void}
+    //  */
+    on ( event, listener ) {
+        return super.on( event, (...args) => {
+            try {
+                return listener.apply( this, args );
+            } catch (error) {
+                console.error( `WARN Socket ${this.id} on( ${String(event)}, ${args.slice(0,-1).join(', ')} ).`, error );
+                // this.warnings.push( {
+                //     msg: `WARN Socket ${this.id} on( ${String(event)}, ${args.slice(0,-1).join(', ')} ).`,
+                //     error: error
+                // } );
+            }
+        });
+    }
+
+    /**
+     * @param { function() : void } callback
+     */
+    onDisconnect ( callback ) {
+        this.on( 'disconnect', callback);
+    }
+
+    /**
+     * @param { IOConfig } config
+     */
+    emitConfig ( config ) {
+        super.emit( 'config', config );
+    }
+
+    /**
+     * @param { number } width
+     * @param { number } height
+     * @param { IOTile [] } tiles
+     */
+    emitMap ( width, height, tiles ) {
+        super.emit( 'map', width, height, tiles );
+    }
+
+    /**
+     * @param { IOTile } tile
+     * @param { IOInfo } info
+     */
+    emitTile ( { x, y, type }, info ) {
+        super.emit( 'tile', {x, y, type}, info );
+    }
+
+    /**
+     * @param { 'connected'|'disconnected' } status
+     * @param { Parameters<IOServerEvents['controller']>[1] } agent
+     */
+    emitController ( status, {id, name, teamId, teamName, score} ) {
+        super.emit( 'controller', status, {id, name, teamId, teamName, score} );
+    }
+    
+    /**
+     * @param { IOAgent } you
+     * @param { IOInfo } info
+     */
+    emitYou ( {id, name, teamId, teamName, x, y, score, penalty}, info ) {
+        super.emit( 'you', {id, name, teamId, teamName, x, y, score, penalty}, info );
+    }
+
+    /**
+     * @param { IOSensing [] } agents
+     * @param { IOInfo } info
+     */
+    emitAgentsSensing ( agents, info ) {
+        super.emit( 'agents sensing', agents, info );
+    }
+    
+    /**
+     * @param { IOSensing [] } parcels
+     * @param { IOInfo } info
+     */
+    emitParcelSensing ( parcels, info ) {
+        super.emit( 'parcels sensing', parcels, info );
+    }
+
+    /**
+     * @param { IOSensing [] } crates
+     * @param { IOInfo } info
+     */
+    emitCrateSensing ( crates, info ) {
+        super.emit( 'crates sensing', crates, info );
+    }
+
+
+
+    /**
+     * @callback onMoveCallback
+     * @param { 'up' | 'right' | 'left' | 'down' | { x:number, y:number } } directionOrXy
+     * @param { function( { x:number, y:number } | false ) : void } replyAcknowledgmentCallback ( reply )
+     */
+    /**
+     * @param { onMoveCallback } callback ( direction, acknowledgementCallback )
+     */
+    onMove ( callback ) {
+        this.on( 'move', callback );
+    }
+    
+    /**
+     * @callback onPickupCallback
+     * @param { function( { id:string } [] ) : void } acknowledgementCallback
+     */
+    /**
+     * @param { onPickupCallback } callback ( acknowledgementCallback )
+     */
+    onPickup ( callback ) {
+        this.on( 'pickup', callback );
+    }
+
+    /**
+     * @callback onPutdownCallback
+     * @param { string [] } selected ids of parcels to drop
+     * @param { function( { id:string } [] ) : void } acknowledgementCallback
+     */
+    /**
+     * @param { onPutdownCallback } callback ( selected, acknowledgementCallback )
+     */
+    onPutdown ( callback ) {
+        this.on( 'putdown', callback );
+    }
+
+
+
+    /**
+     * @param { function ( string, any, function ( 'successful' ) : void ) : void } callback ( toId, msg, ack )
+     */
+    onSay ( callback ) {
+        this.on( 'say', callback );
+    }
+
+    /**
+     * @param { function ( string, any, function ( any ) : void ) : void } callback ( toId, msg, ack(reply) )
+     */
+    onAsk ( callback ) {
+        this.on( 'ask', callback );
+    }
+
+    /**
+     * @param { function ( any, function ( any ) : void ) : void } callback ( msg, ack(reply) )
+     */
+    onShout ( callback ) {
+        this.on( 'shout', callback );
+    }
+
+    /**
+     * @param { IOAgent } me
+     * @param { string } toId
+     * @param { {} } msg
+     * @returns { Promise < any > } reply
+     */
+    async emitMsg ( me, toId, msg ) {
+        return super.to( "agent:" + toId ).emit( 'msg', me.id, me.name, msg );
+    }
+
+    /**
+     * @param { IOAgent } me
+     * @param { string } toId
+     * @param { {} } msg
+     * @returns { Promise < any > } reply
+     */
+    async emitAsk ( me, toId, msg ) {
+        
+        // Currently, acks is awaited from all clients when .emit(), otherwise callback gets an error
+        // https://github.com/socketio/socket.io/discussions/5062
+        const sockets = await super.to( "agent:" + toId ).fetchSockets();
+        const emissionPromises = sockets.map( socket => {
+            return new Promise( (res) => {
+                socket.timeout(1000).emit( 'msg', me.id, me.name, msg, (err, response) => {
+                    if (err)
+                        res('timeout');
+                    else
+                        res(response);
+                } );
+            } );
+        } );
+
+        // wait for first promise to resolve and ensure a timeout resolution in case all the responses are invalid
+        const response = await Promise.race(
+            emissionPromises.concat(new Promise(res => setTimeout(() => res('timeout'), 1000)))
+        );
+
+        return response;
+    }
+
+    /**
+     * @param { any } msg
+     * @returns { void } reply
+     */
+    broadcastMsg ( me, msg ) {
+        super.broadcast.emit( 'msg', me.id, me.name, msg );
+    }
+
+    /**
+     * @param { function ( ...any ) : void } callback ( ...msgArgs )
+     */
+    onLog ( callback ) {
+        this.on( 'log', callback );
+    }
+    
+    /**
+     * @param { string } myId
+     * @param { string } myName
+     * @param { 'server' | { socket:string, id:string, name:string } } src - 'server' or client
+     * @param { IOInfo } info
+     * @param { ...any } message
+     */
+    broadcastLog ( myId, myName, src, info, ...message ) {
+        super.broadcast.emit( 'log', src, info, ...message );
+    }
+
+
+
+    /**
+     * Process request for creating a parcel on x, y or disposing or setting its reward given the id
+     * @param { function ( 'create' | 'dispose' | 'set', {id:string, x:number, y:number, reward:number} ) : void } callback 
+     */
+    onParcel ( callback ) {
+        this.on( 'parcel', callback );
+    }
+
+    /**
+     * Process request for creating a tile on x, y or setting its type
+     * @param { function ( IOTile ) : void } callback
+     */
+    onTile ( callback ) {
+        this.on( 'tile', callback );
+    }
+
+    /**
+     * Process request for restarting the game
+     * @param { function () : void } callback
+     */
+    onRestart ( callback ) {
+        this.on( 'restart', callback );
+    }
+
+
+
+    /**
+     * Enhance a Socket.io Socket into a DjsSocket
+     * @param { Socket } socket
+     * @returns { DjsServerSocket }
+     */
+    static enhance(socket) {
+
+        /**
+         * Mixin function to copy methods from a class prototype to an object
+         */
+        function applyMixin(target, MixinClass) {
+            
+            let proto = MixinClass.prototype;
+
+            const descriptors = Object.getOwnPropertyDescriptors(proto);
+            delete descriptors.constructor;
+            
+            Object.defineProperties(target, descriptors);
+
+            return target;
+        }
+        applyMixin(socket, DjsServerSocket);
+
+        /**
+         * Original socket enhanced with ClientSocketEnhancer methods casted as EnhancedSocket
+         * @type { DjsServerSocket }
+        */
+    // @ts-ignore
+        return socket;
+
+    }
+
+}
+
+
+
+
+// import { Server } from 'socket.io';
+// const ioserver = new Server();
+// ioserver.listen( 3000 );
+// ioserver.on( 'connection', ( socket ) => {
+//     const enhancedSocket = enhanceServerSocket( socket );
+//     enhancedSocket.onMove( ( direction ) => {
+//         console.log( `Client ${enhancedSocket.id} moved ${direction}` );
+//         return { success: true };
+//     } );
+// } );

package/src/server/index.js

@@ -0,0 +1,21 @@
+
+/**
+ * @typedef {import("../types/IOConfig.js").IOConfig} IOConfig
+ * @typedef {import("../types/IOGameOptions.js").IOGameOptions} IOGameOptions
+ * 
+ * @typedef {import("../types/IOClockEvent.js").IOClockEvent} IOClockEvent
+ * 
+ * @typedef {import("../types/IOAgent.js").IOAgent} IOAgent
+ * @typedef {import("../types/IOParcel.js").IOParcel} IOParcel
+ * @typedef {import("../types/IOTile.js").IOTile} IOTile
+ * 
+ * @typedef {import("../types/IOIdentity.js").IOIdentity} IOIdentity
+ * @typedef {import("../types/IOInfo.js").IOInfo} IOInfo
+ * @typedef {import("../types/IOSensing.js").IOSensing} IOSensing
+ * 
+ * @typedef {import("../types/IOSocketEvents.js").IOClientEvents} IOClientEvents
+ * @typedef {import("../types/IOSocketEvents.js").IOServerEvents} IOServerEvents
+ */
+
+export { DjsServerSocket } from './DjsServerSocket.js';
+export { DjsServer } from './DjsServer.js';

package/src/types/IOAgent.js

@@ -0,0 +1,14 @@
+
+/**
+ * @typedef IOAgent
+ * @property {string} id
+ * @property {string} name
+ * @property {string} teamId
+ * @property {string} teamName
+ * @property {number} x
+ * @property {number} y
+ * @property {number} score
+ * @property {number} penalty
+ */
+
+export { };

package/src/types/IOClockEvent.js

@@ -0,0 +1,21 @@
+
+/**
+ * @typedef { 'frame' | '1s' | '2s' | '5s' | '10s' | 'infinite' } IOClockEvent
+ * @export
+ */
+
+
+
+/**
+ * @param { string } event
+ * @returns { IOClockEvent }
+ */
+function parseClockEvent ( event ) {
+    if ( event == 'frame' || event == '1s' || event == '2s' || event == '5s' || event == '10s' || event == 'infinite' )
+        return event;
+    else
+        console.warn( `IOClockEvent: invalid event '${event}', defaulting to '1s'` );
+        return '1s';
+}
+
+export { parseClockEvent };

package/src/types/IOConfig.js

@@ -0,0 +1,17 @@
+
+/**
+ * @typedef { import("./IOGameOptions.js").IOGameOptions } IOGameOptions
+ */
+
+/**
+ * @typedef IOConfig
+ * 
+ * config.js
+ * @property {Number} CLOCK                     Game clock event name
+ * @property {Number} PENALTY                   Penalty for wrong moves
+ * @property {Number} AGENT_TIMEOUT             Player/Controller timeout
+ * @property {Boolean} BROADCAST_LOGS           Whether to broadcast logs to clients
+ * @property {IOGameOptions} GAME               Game options
+ */
+
+export { };

package/src/types/IOCrate.js

@@ -0,0 +1,9 @@
+
+/**
+ * @typedef IOCrate
+ * @property {string} id
+ * @property {number} x
+ * @property {number} y
+ */
+
+export { };

package/src/types/IOGameOptions.js

@@ -0,0 +1,54 @@
+
+/** @typedef { import("./IOClockEvent.js").IOClockEvent } IOClockEvent */
+/** @typedef { import("./IOTile.js").IOTileType } IOTileType */
+
+/**
+ * @typedef IOGameOptions
+ * 
+ * config.js
+ * @property {string} title                             Game title
+ * @property {string} description                       Game description
+ * @property {IOMapOptions} map                         Map configuration
+ * @property {number} maxPlayers                        Maximum number of players
+ * @property {IONpcsOptions[]} npcs                     Array of NPC configurations
+ * @property {IOParcelsOptions} parcels                 Parcels configuration
+ * @property {IOPlayerOptions} player                   Player configuration * 
+ */
+
+/**
+ * @typedef IOMapOptions
+ * @property {number} width                             Map width in tiles
+ * @property {number} height                            Map height in tiles
+ * @property {IOTileType[][]} tiles                     2D array of tile types
+*/
+
+/**
+ * @typedef IONpcsOptions
+ * NPC configuration object
+ * @property {IOClockEvent} moving_event                Event whenever the NPC moves
+ * @property {string} type                              NPC type (random, collector, etc.)
+ * @property {number} count                             Number of NPCs of this type
+ * @property {number} capacity                          Capacity (for collector NPCs)
+*/
+
+/**
+ * @typedef IOParcelsOptions
+ * Parcels configuration object
+ * @property {IOClockEvent} generation_event            Event for parcels generation
+ * @property {IOClockEvent} decaying_event              Event for parcel decaying
+ * @property {number} max                               Maximum number of parcels in the grid
+ * @property {number} reward_avg                        Reward average
+ * @property {number} reward_variance                   Reward variance
+*/
+
+/**
+ * @typedef IOPlayerOptions
+ * Player configuration object
+ * @property {string} agent_type                        Agent class
+ * @property {number} movement_duration                 Duration of each movement in ms
+ * @property {number} agents_observation_distance       Observation distance for agents
+ * @property {number} parcels_observation_distance      Observation distance for parcels
+ * @property {number} capacity                          Capacity
+ */
+
+export { };

package/src/types/IOIdentity.js

@@ -0,0 +1,12 @@
+
+/**
+ * @typedef IOIdentity
+ * @type {{
+ *   id: string,
+ *   name: string,
+ *   teamId: string,
+ *   teamName: string
+ * }}
+ */
+
+export {};

package/src/types/IOInfo.js

@@ -0,0 +1,11 @@
+
+/**
+ * @typedef IOInfo
+ * @property {number} ms
+ * @property {number} frame
+ * @property {number} fps
+ * @property {number} heapUsed
+ * @property {number} heapTotal
+ */
+
+export { };

package/src/types/IOParcel.js

@@ -0,0 +1,11 @@
+
+/**
+ * @typedef IOParcel
+ * @property {string} id
+ * @property {number} x
+ * @property {number} y
+ * @property {string=} carriedBy
+ * @property {number} reward
+ */
+
+export { };

package/src/types/IOSensing.js

@@ -0,0 +1,15 @@
+
+/** @typedef {import('./IOAgent.js').IOAgent} IOAgent */
+/** @typedef {import('./IOParcel.js').IOParcel} IOParcel */
+/** @typedef {import('./IOCrate.js').IOCrate} IOCrate */
+
+/**
+ * @typedef IOSensing
+ * @property {number} x
+ * @property {number} y
+ * @property {IOAgent=} agent
+ * @property {IOParcel=} parcel
+ * @property {IOCrate=} crate
+ */
+
+export { };

package/src/types/IOSocketEvents.js

@@ -0,0 +1,44 @@
+
+/** @typedef {import('./IOAgent.js').IOAgent} IOAgent */
+/** @typedef {import('./IOTile.js').IOTile} IOTile */
+/** @typedef {import('./IOInfo.js').IOInfo} IOInfo */
+/** @typedef {import('./IOSensing.js').IOSensing} IOSensing */
+
+/**
+ * Client -> Server events. Emitted by the client and listened by the server.
+ * @typedef {{
+ *      'disconnect':   function () : void,
+ *      'move':         function ( 'up' | 'right' | 'left' | 'down' | { x:number, y:number }, function ( { x:number, y:number } | false ) : void = ) : { x:number, y:number } | false,
+ *      'pickup':       function ( function ( { id:string } [] ) : void = ) : { id:string } [],
+ *      'putdown':      function ( string [] =, function ( { id:string } [] ) : void = ) : { id:string } [],
+ *      'say':          function ( string, any, function( 'successful' ) : void ) : void,
+ *      'ask':          function ( string, any, function( any ) : void ) : void,
+ *      'shout':        function ( any, function( any ) : void ) : void,
+ *      'parcel':       function ( 'create' | 'dispose' | 'set', { x:number, y:number } | { id:string, reward?:number } ) : void,
+ *      'crate':        function ( 'create' | 'dispose', { x:number, y:number } ) : void,
+ *      'restart':      function () : void,
+ *      'tile':         function ( IOTile ) : void,
+ *      'log':          function ( ...any ) : void
+ * }} IOClientEvents
+ */
+
+/**
+ * Server -> Client events. Emitted by the server and listened by the client.
+ * @typedef {{
+ *      'connect':          function () : void,
+ *      'disconnect':       function () : void,
+ *      'token':            function ( string ) : void,
+ *      'config':           function ( any ) : void,
+ *      'map':              function ( number, number, IOTile[] ) : void,
+ *      'tile':             function ( IOTile, IOInfo ) : void,
+ *      'controller':       function ( 'connected' | 'disconnected', {id:string, name:string, teamId:string, teamName:string, score:number} ) : void,
+ *      'you':              function ( IOAgent, IOInfo ) : void,
+ *      'agents sensing':   function ( IOSensing[], IOInfo ) : void,
+ *      'parcels sensing':  function ( IOSensing[], IOInfo ) : void,
+ *      'crates sensing':   function ( IOSensing[], IOInfo ) : void,
+ *      'msg':              function ( string, string, Object, function ( Object ) : void = ) : Object,
+ *      'log':              function ( 'server' | { socket:string, id:string, name:string }, IOInfo, ...any ) : void
+ * }} IOServerEvents
+ */
+
+export { };

package/src/types/IOTile.js

@@ -0,0 +1,28 @@
+
+/**
+ * @typedef IOTileType
+ * Tile type representation (string)
+ * @type { '0' | '1' | '2' | '3' | '4' | '5' | '5!' | '←' | '↑' | '→' | '↓' }
+*/
+
+/**
+ * @typedef IOTile
+ * @property {number} x
+ * @property {number} y
+ * @property {IOTileType} type - Tile type: '0' (wall), '1' (parcel spawner), '2' (delivery), '3' (walkable), '4' (base), '5' (crate sliding tile), '5!' (crate spawner), or directional arrows '↑', '→', '↓', '←'
+ */
+
+/**
+ * @param {number | string} typeStr
+ * @returns {IOTileType}
+ */
+export function parseIOTileType(typeStr) {
+    typeStr = String(typeStr);
+    const validTypes = ['0', '1', '2', '3', '4', '5', '5!', '←', '↑', '→', '↓'];
+    if ( validTypes.includes(typeStr[0]) && typeStr[1] == '!' || typeStr.length === 1 ) {
+        return /** @type {IOTileType} */ (typeStr);
+    } else {
+        console.warn(`Invalid IOTileType: ${typeStr}, defaulting to '0'`);
+        return '0';
+    }
+}

package/src/types/parseClockEvent.js

@@ -0,0 +1,17 @@
+
+/** @typedef {import("./IOClockEvent.js").IOClockEvent} IOClockEvent */
+
+
+
+/**
+ * @param { string } event
+ * @returns { IOClockEvent }
+ */
+function parseClockEvent ( event ) {
+    if ( event == 'frame' || event == '1s' || event == '2s' || event == '5s' || event == '10s' )
+        return event;
+    else
+        throw new Error( `IOClockEvent: invalid event '${event}'` );
+}
+
+export { parseClockEvent };