20090403-1606

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)