diff options
| -rw-r--r-- | appl/spree/man/gamesrv.man2 | 471 | ||||
| -rw-r--r-- | appl/spree/man/gamesrv.man4 | 296 |
2 files changed, 0 insertions, 767 deletions
diff --git a/appl/spree/man/gamesrv.man2 b/appl/spree/man/gamesrv.man2 deleted file mode 100644 index fd910519..00000000 --- a/appl/spree/man/gamesrv.man2 +++ /dev/null @@ -1,471 +0,0 @@ -.TH GAMESRV 2 -.SH NAME -Gamesrv \- game server module -.SH SYNOPSIS -.EX -.ps -1 -.vs -1 -include "draw.m"; -include "gamesrv.m"; -gamesrv := load Gamesrv Gamesrv->PATH; -Range, Object, Game, Player: import gamesrv; - -Range: adt { - start: int; - end: int; -}; - -Object: adt { - transfer: fn(o: self ref Object, - r: Range, dst: ref Object, i: int); - setvisibility: fn(o: self ref Object, - visibility: int); - setattrvisibility: fn(o: self ref Object, - name: string, visibility: int); - setattr: fn(o: self ref Object, - name: string, val: string, vis: int); - getattr: fn(o: self ref Object, name: string): string; - delete: fn(o: self ref Object); - deletechildren: fn(o: self ref Object, r: Range); - - id: int; - parentid: int; - children: array of ref Object; - objtype: string; - visibility: int; - # ...private data - -}; - -Game: adt { - newobject: fn(game: self ref Game, parent: ref Object, - visibility: int, objtype: string): ref Object; - action: fn(game: self ref Game, cmd: string, - objs: list of int, rest: string, whoto: int); - player: fn(game: self ref Game, id: int): ref Player; - - objects: array of ref Object; - # ...private data -}; - -Player: adt { - name: fn(player: self ref Player): string; - hangup: fn(player: self ref Player); - obj: fn(player: self ref Player, id: int): ref Object; - - id: int; - # ...private data -}; - -Gamemodule: module { - clienttype: fn(): string; - init: fn(game: ref Gamesrv->Game, srvmod: Gamesrv): string; - command: fn(player: ref Gamesrv->Player, e: string): string; - join: fn(player: ref Gamesrv->Player): string; - leave: fn(player: ref Gamesrv->Player); -}; - -rand: fn(n: int): int; -.ps +1 -.vs +1 -.EE -.SH DESCRIPTION -.I Gamesrv -provides a general server interface that allows distributed -clients to interact in a controlled manner, with the -interaction mediated -by Limbo modules, known as -.IR "game engines" , -or just -.I engines -for short. -Each engine decides on the rules -of its particular game; the engine interface is described -at the end of this manual page, under -``Module Interface''. -.PP -This manual page describes the -interface as presented to an engine -once it has been loaded by -.IR gamesrv . -An engine is responsible for a particular -.IR game , -in which one or more -.I players -participate. Messages sent by players -are interpreted by the game engine, which -responds by making changes to the hierarchical -.I object -database held by the game. -Behind the scenes -.I gamesrv -distributes updates to this database to players -of the game as appropriate. -.SS "Objects and visibility" -Objects hold a game's visible state. An object -has a unique integer -.IR id , -which is an index into the array -.IB game .objects\fR;\fP -it also holds a set of attribute-value pairs, a type, and -zero or more child objects. Together, all the objects -in the game form a hierarchical tree, rooted at -the -.IR "root object" -(id 0), which always exists. -Each attribute and each object also has an associated -.IR "visibility set" , -the set of players that sees updates to the attribute or the children -of the object. A visibility set is an integer, a bitmask where each -bit represents one player, hence -.B ~0 -is visible to all players, and -.B 0 -is visible to no-one. -In general, each player has a unique -identifier -.IR id ; -in an integer -.I i -representing a set of players, -the -.IR id th -bit represents the presence of the player with -identifier -.IR id . -Thus, for a player -.IR p , -.BI "(1<<" p ".id)" -is the set containing only -.IR p , -.BI "(" i "&~(1<<" p ".id))" -excludes -.I p -from the set, and -.BI "(" i "|(1<<" p ".id))" -includes -.I p -in the set. -.PP -Note that the visibility set of an object does not alter the visibility -of that object's attributes, but only that of its children (and of -their children: in general an object is visible to a player if the -intersection of all its ancestors' visibility sets contains that -player). -.PP -Objects can be transferred inside the hierarchy from one parent to -another. If an object is moved to a parent whose visibility conceals it -from a player, then it will appear to that player to have been deleted; -if it is later made visible, then it will be recreated for that -player. -A game engine can almost always ignore this technicality, -except for one thing: the identifier used by a particular player to -identify an object is not necessarily the same as that used by the game -engine. Thus when an engine receives an object id in a player's -message, it should convert it using the -.IB player .obj() -function. -.SS \fBGame\fP -The -.B Game -type holds all the objects in a game. It allows the -creation of new objects, and provides way of communicating -with players outside the object hierarchy. -All data members of a -.B Game -should be treated as read-only. -.TP 10 -.IB game .objects -This array holds the objects in the game. An object with -identifier -.I id -is found at -.IB game .objects[ id ]\fR.\fP -.TP -.IB game .newobject(\fIparent\fP,\ \fIvisibility\fP,\ \fIobjtype\fP) -.B Newobject -creates a new object at the end -of -.IR parent 's -children; -If -.I parent -is nil, the new object is created under the root object. -The new object has visibility -.IR visibility , -and type -.IR objtype . -An object's type cannot be changed once -it has been created. -.TP -.IB game .action(\fIcmd\fP,\ \fIobjs\fP,\ \fIrest\fP,\ \fIwhoto\fP) -.B Action -sends a message to some players without affecting -the object hierarchy. It can be used to send transient -events that have no meaning when stored statically -(for example, network latency probes). -The message is sent to the set of players given by -.IR whoto . -.I Objs -is assumed to be a list of object ids, which are -converted appropriately for each player -receiving the message; the final -message is a string built by concatenating -.IR cmd , -the list of object ids, and -.IR rest , -separated by spaces. -.TP -.IB game .player(\fIid\fP) -.B Player -yields the player corresponding to identifier -.IR id , -or -.B nil -if there is none. -.SS Player -The -.B Player -type represents a player of a game. -.TP 10 -.IB player .id -The player's identifier, an integer between -0 and 31. This is unique across all current players, -but ids of players that have left the game will -be reused. -.TP -.IB player .obj(\fIid\fP) -.B Obj -converts from a player's external object -identifier to the game's local -.B Object -that it represents. It returns -.B nil -if there is no such object. -.TP -.IB player .hangup() -.B Hangup -hangs up a player's connection to the game; -no more requests from -.I player -will be received by the game engine. -.TP -.IB player .name() -.B Name -yields the authenticated name of the player. -This is not necessarily unique over the players -of a game. -.SS \fBObject\fP -The -.B Object -type is the basic unit of game engine state. -An object's children can be selectively concealed -from players; it holds a set of -.RI ( attribute ,\ value ) -pairs, each of which can be concealed likewise. -Where an argument -.IR r , -of -.B Range -type is used, it refers to a range of an object's -children starting at index -.IB r .start\fR,\fP -and finishing at -.IB r .end-1\fR.\fP -All the data members of an -.B Object -should be treated as read-only. -.TP 10 -.IB obj .setattr(\fIname\fP,\ \fIval\fP,\ \fIvis\fP) -.B Setattr -sets attribute -.I name -in -.I obj -to -.IR val. -If the attribute is being created for the -first time, then it will be given visibility -.IR vis . -.I Name -should be non-empty, and should not -contain any space characters. -Note that it is not possible for an attribute -to refer directly to an object by its identifier; -if this facility is needed, another identifying -scheme should be used. This also applies -to player identifiers, which will change -if the game is saved and loaded again (not -implemented yet). -.TP -.IB obj .getattr(\fIname\fP) -.B Getattr -yields the current value of the -attribute -.I name -in -.IR obj . -If an attribute is not set, it yields -.BR nil . -.TP -.IB obj .delete() -.B Delete -removes -.I obj -from the object -hierarchy. -.TP -.IB obj .deletechildren(\fIr\fP) -.B Deletechildren -deletes children in range -.I r -from -.IR obj . -.TP -.IB obj .transfer(\fIr\fP,\ \fIdst\fP,\ \fIi\fP) -.B Transfer -transfers the children in range -.I r -from -.I obj -to just before the object at index -.I i -in -.IR dst . -It is permissible for -.I obj -and -.I dst -to be the same object. -.TP -.IB obj .setvisibility(\fIvisibility\fP) -.B Setvisibility -allows the set of players -given in -.I visibility -to see the children of -.IR obj , -and denies access to all others. -Players are notified of the change. -.TP -.IB obj .setattrvisibility(\fIname\fP,\ \fIvisibility\fP) -.B Setattrvisibility -allows the set of players -given in -.I visibility -to see the value of -.IR obj 's -attribute -.IR name , -and denies access to all others. -Players are not notified of the change; -if there is a need to communicate -the fact of an attribute becoming invisible to -players, it should be done by using another -(visible) attribute to communicate the change. -.SS "Module Interface" -A game engine module, -.IR mod , -must implement the -following functions. Where a function returns a string, -it is interpreted as an error response to the player -responsible for the request; an empty string signifies -no error. -.TP -.IB mod .clienttype() -.B Clienttype -should return the type of client required -by the engine (e.g. -.B cards -for the card-game client). -Each client type has its own conventions -as to the meaning of object types and attribute -names and values. -This function may be called before -.BR init() . -.TP -.IB mod .init(\fIgame\fP,\ \fIsrvmod\fP) -.B Init -initialises the game engine. -.I Game -is the game that the engine is controlling, -and -.I srvmod -is the -.B Gamesrv -module holding its associated data. -An error response from this function -causes the game to be aborted. -.TP -.IB mod .join(\fIplayer\fP) -.I Player -has made a request to join the game; -an error response causes the request to be -refused, otherwise the player joins the -game. -.TP -.IB mod .leave(\fIplayer\fP) -.I Player -has left the game. -.TP -.IB mod .command(\fIplayer\fP,\ \fIe\fP) -.I Player -has sent the command -.IR e . -The command usually follows -the simple message conventions -used in -.IR gamesrv (4), -i.e. simple space-separated tokens. -.SH EXAMPLE -The following is a small, but working example -of a game engine that acts as a chat server -(parsing error checking omitted, and white-space -compressed to save paper): -.PP -.EX -.ps -1 -.vs -1 -implement Gamemodule; -include "sys.m"; - sys: Sys; -include "draw.m"; -include "../gamesrv.m"; - gamesrv: Gamesrv; - Game, Player: import gamesrv; -game: ref Game; -clienttype(): string -{ - return "chat"; -} -init(g: ref Game, srvmod: Gamesrv): string -{ - (sys, game, gamesrv) = (load Sys Sys->PATH, g, srvmod); - return nil; -} -join(nil: ref Player): string -{ - return nil; -} -leave(nil: ref Player) -{ -} -command(player: ref Player, cmd: string): string -{ - game.action("say " + string player.id + " " + cmd, nil, nil, ~0); - return nil; -} -.ps +1 -.vs +1 -.EE -.SH SOURCE -.B /appl/cmd/games/gamesrv.b -.SH "SEE ALSO" -.IR gamesrv (4) -.SH BUGS -The reuse of object ids can lead to -problems when objects are deleted and -recreated on the server before clients become -aware of the changes. -.PP -This interface is new and will change. diff --git a/appl/spree/man/gamesrv.man4 b/appl/spree/man/gamesrv.man4 deleted file mode 100644 index 5db352b3..00000000 --- a/appl/spree/man/gamesrv.man4 +++ /dev/null @@ -1,296 +0,0 @@ -.TH GAMESRV 4 -.SH NAME -gamesrv \- game server -.SH SYNOPSIS -.B games/gamesrv -[ -.B -l -] [ -.B -a -.I alg -]... -[ -.B -A -] [ -.IR addr | mntpoint -] -.PP -.IB mntpoint /players -.br -.IB mntpoint /new -.br -.IB mntpoint / n -.SH DESCRIPTION -.B Gamesrv -serves a file system that allows clients to interact -through various types of game engine. -Usually, it operates in network mode: -it listens for incoming connections on -.I addr -(default -.BR tcp!*!3242 ), -authenticates them, and serves files to them. -If the -.B -A -option is given, no authentication takes place, -otherwise each -.I alg -gives an additional possible -encryption or digest algorithm to use -on the connection (see -.IR ssl (3)). -If no -.I alg -is specified, -.B none -is assumed. -The -.B -l -option causes the game server to be mounted -locally on -.I mntpoint -\- this can be useful for single player games, -or debugging. -.PP -Once the name-space served by -.I gamesrv -is mounted, it serves the following files. -All identifiers referred to below are -small integers, expressed as decimal ASCII strings. -.TP -.B players -Reading this file provides updates on players -arriving and leaving, games being created -and destroyed, and chat messages outside -the scope of any game. -Reads will block until something of interest happens. -Each update holds space separated -tokens and is terminated with a newline. -A read will return as many updates as will fit -into the read buffer. Update messages are as follows: -.RS -.TP -.BI clientid " clientid name" -Identifies the name, -.IR name , -and the client identifier, -.IR clientid , -of the client -reading the players file. -.TP -.BI join " clientid name" -A client has authenticated as -.IR name , -and has been allocated identifier -.IR clientid . -.TP -.BI leave " clientid" -The client identified by -.I clientid -has terminated connection with the server. -.TP -.BI gametype " clienttype name" -The server announces the availability of a game -named -.I name -on the server. The game requires a client of -type -.I clienttype -to display the game. -.TP -.BI creategame " gameid name clienttype" -An instance of a game named -.IR name -has been created; it needs a client -of type -.IR clienttype , -and has been given identifier -.IR gameid . -.TP -.BI deletegame " gameid" -The game identified by -.I gameid -has been deleted. -.TP -.BI joingame " gameid clientid playerid name" -Client -.I clientid -(named -.IR name ) -has joined game -.I gameid , -and is allocated player id -.I playerid -in the game. -.TP -.BI leavegame " gameid playerid name" -Player -.I playerid -(named -.IR name ) -has left -.IR gameid . -.TP -.BI chat " clientid msg" -Client -.I clientid -has sent the chat message -.IR msg . -.PP -Writing to the -.B players -file causes a -.B chat -message to be sent to all other clients reading -the players file. All but the first line of the -write request is ignored. -.RE -.TP -.B new -Opening -.B new -prepares to create a new game. -The only message that can be written -to a newly opened game is -.BI \fR``\fPcreate " name"\fR'',\fP -to request a new game named -.IR name . -The write request draws an error -if -.I gamesrv -fails to find and load the requisite game -engine. -If the write succeeds, the game is created, -and game updates can be read in the same -manner as from the -.B players -file. The update messages are as follows: -.RS -.TP -.BI playerid " clientid playerid name" -Identifies the player identifier, -.IR playerid , -and name, -.IR name , -of the reader. -.TP -.BI create " objid parentid visibility objtype" -Create an object, identified by -.IR objid , -at the end of -.IR parentid 's -children -.RI ( parentid -is -.B -1 -for the root object). -.I Visibility -is the visibility set of the object (see -.IR gamesrv (2)), -and -.I objtype -is its type. -.TP -.BI tx " srcid dstid start end index" -Transfer objects from -.I srcid -to -.IR dstid. -Take the objects from the range -.RI [ start ,\ end ) -in the children of -.IR srcid , -and insert them just before -.I index -in -.IR dstid . -Note that when objects are transferred -to an object that conceals its children, -and the object is itself visible, -the objects will first be transferred to the -destination and then deleted; objects transferred -out of such an object will first be created and -.I then -transferred to their destination. -This enables a client to maintain some knowledge -of where an object has been transferred to, even -if the object is no longer visible. -.TP -.BI del " parentid start end" -Delete the range -.RI [ start ,\ end ) -of children from the object identified by -.IR parentid . -.I Gamesrv -guarantees that those objects will themselves -not have any children. -.TP -.BI set " objid attr val" -Set the attribute named -.I attr -on object -.I objid -to -.IR val . -.TP -.BI vis " objid visibility" -The visibility of object -.I objid -has changed to -.IR visibility . -.TP -.I action -Game engines can generate arbitrary messages -of their own devising; such messages are specific -to particular client types. -.PP -Note that a given client does not have to interpret -all the above messages \- different client types -have their own conventions. The -.B card -client type uses most of the above functionality, -for example, whereas a client for the -.B chat -engine listed in -.IR gamesrv (2) -can get away with interpreting only one message, the custom action -.BR chat . -.PP -Writes to the opened game file -are interpreted as game actions by -the game that has been loaded, and acted on accordingly. -Invalid actions will draw a write error. -.RE -.TP -.I n -Once a game has been created, it appears as -a numbered file, corresponding to the -.I gameid -of the game in question. -Opening this file joins the game; reads and writes -work as for the -.B new -file, above. -A single client cannot join a particular game -more than once. -.PP -A zero-length write to any file causes any reads -of that file from the same file descriptor to yield -EOF (no bytes). -This is necessary to force a hangup under -systems such as Windows, where it is not possible -to interrupt a kproc blocked on a network read. -.SH EXAMPLE -The simplest client! -.PP -.EX -mount tcp!somehost.com!3242 /n/remote -{ - echo create chat >[1=0] - cat & - cat >[1=0] < /dev/cons -} <> /n/remote/new -.SH SOURCE -.B /appl/cmd/games/gamesrv.b -.SH SEE ALSO -.IR gamesrv (2) |