asterism-games 0.22.0 → 0.23.0

data/lib/asterism_games/commentate.rb

@@ -34,7 +34,7 @@ module AsterismGames
         --namespace PREFIX    a room's tables (room/01: their spectate keys room01-<table>,
                               outside the room; the connection itself has no namespace)
         --table TABLE         the table to show first (<table>, <host>/<table>, or
-                              <host>/spectate/<table>); without it every table that puts
+                              <host>/@shared/spectate/<table>); without it every table that puts
                               its spectate key is listed and the first one shown
         --node NODE           the node ID (default: commentate-<host>-<pid>, or the .tar's name)
         --port N              the page's port on 127.0.0.1 (default %<port>d; taken: the next free)

data/lib/asterism_games/game.rb

@@ -36,6 +36,17 @@ module AsterismGames
   #   SAVE_HOLD_MS           at most one write of the saved state this often (0: after
   #                          every change); a game that changes many times a second
   #                          (the board's strokes) holds its writes
+  #   TYPES                  the types of what the host puts (asterism's docs/protocol.md
+  #                          11.2): {name => [[[field, type], ...], text]}, told to the
+  #                          readers by the host's @profile?types
+  #   STATE_TYPE             the type of <table>/state (a name of TYPES; nil: none)
+  #   TOLD_TYPES             {sub => type} of what the game tells (tell(sub, value))
+  #   SPECTATE_TYPE          the type of what spectate_view gives (a name of
+  #                          SPECTATE_TYPES; nil: none), the topic
+  #                          spectate/<table>/state of the node's shared place
+  #                          (README "Spectate")
+  #   SPECTATE_TYPES         the types of it, as TYPES; defined on the connection
+  #                          that puts it (a connection's types are its own)
   #
   # and writes the rules: tick(now), public_view(now) (and spectator_view,
   # summary when they differ; spectate_view and spectate_delay_ms for what
@@ -60,6 +71,13 @@ module AsterismGames
   class Game
     SAVE_FORMAT = 1
     SAVE_HOLD_MS = 0
+    TYPES = {}.freeze
+    STATE_TYPE = nil
+    TOLD_TYPES = {}.freeze
+    SPECTATE_TYPE = nil
+    SPECTATE_TYPES = {}.freeze
+    # The namespace of the types' names (asterism-games/<game>.<what>).
+    TYPE_PREFIX = "asterism-games/"
     MAX_MEMBERS = 16
     NAME_MAX = 32
 
@@ -156,7 +174,8 @@ module AsterismGames
     end
 
     # What those who watch from outside the table see (README "Spectate"):
-    # the host puts it on asterism/<node>/spectate/<table>/state (a room's
+    # the host puts it on asterism/<node>/@shared/spectate/<table>/state
+    # (a topic of the node's shared place, of type SPECTATE_TYPE; a room's
     # table: room<slot>-<table>), a key no player's role reads and outside
     # every room, after spectate_delay_ms. It may hold what the players do
     # not see of each other (the mahjong hands), never what nobody knows

data/lib/asterism_games/host.rb

@@ -13,14 +13,24 @@ module AsterismGames
   # table in the settings, moves the games on, saves them after every change
   # and puts their public state on asterism/<node>/<app>/<table>/state.
   #
-  # One process is one Asterism application (the gem keeps one connection a
-  # process), so every game lives under the same app, each as an object of
-  # its own name. The games come from the registry (AsterismGames.games):
-  # a table's "game" names one.
+  # What it puts on its application's keys are topics (asterism's
+  # docs/protocol.md 9-11): <table>/state and what a game tells
+  # (<table>/<sub>), declared with the game's types (Game::STATE_TYPE,
+  # TOLD_TYPES) and the types defined (Game::TYPES), so a reader finds them
+  # with @profile?pubs;types before a value comes, and each value carries
+  # its sequence number.
+  #
+  # Every game lives under the host's application (config "app"), each as
+  # an object of its own name. The games come from the registry
+  # (AsterismGames.games): a table's "game" names one. What spectators see
+  # from outside the tables goes on the node's shared place
+  # (asterism/<node>/@shared/spectate/..., README "Spectate"), declared by
+  # the host's application, and in a room by the room's application
+  # room<slot> outside the room.
   #
   # The connection is Asterism's block API (Asterism.connect { |net| }):
   # the tables are exposed with caller: :from, and the calls are answered
-  # on the Net's receiving thread. The games move on in this host's own
+  # on the connection's receiving thread. The games move on in this host's own
   # loop (step: timeouts, CPU turns, the puts), which takes Asterism::LOCK,
   # the lock every tick of the receiving thread holds, so a call and a step
   # never meet inside a game.
@@ -180,6 +190,7 @@ module AsterismGames
         net.expose(name, @remotes[name], methods: @methods[name], caller: :from, **extra)
       end
       @net = net
+      declare_topics(net)
       @connected = true
       @tables_status = TablesStatus.new(net, node, @config["app"]) if tables_status?
       write_status
@@ -197,7 +208,7 @@ module AsterismGames
           @log.call("games: connection lost: #{net.lost_reason}")
           return
         end
-        open_spectate
+        open_room_app
         ::Asterism::LOCK.synchronize { step }
         sleep LOOP_S
       end
@@ -208,21 +219,11 @@ module AsterismGames
     # runs other applications too is away as soon as its table app closes.
     PLAYER_APP = "game"
 
-    # Who is there: Asterism's on_app_join / on_app_leave (asterism after
-    # 0.7.1), else a liveliness watch of asterism/*/game on the session.
+    # Who is there: Asterism's on_app_join / on_app_leave.
     def follow_players(net)
       app = @config["player_app"] || PLAYER_APP
-      if net.respond_to?(:on_app_join)
-        net.on_app_join { |n, a| node_joined(n) if a == app }
-        net.on_app_leave { |n, a| node_left(n) if a == app }
-      else
-        own = "asterism/#{node}/"
-        net.session.liveliness_watch("asterism/*/#{app}") do |key, alive|
-          next if key.start_with?(own)
-          n = key.split("/")[1]
-          alive ? node_joined(n) : node_left(n)
-        end
-      end
+      net.on_app_join { |n, a| node_joined(n) if a == app }
+      net.on_app_leave { |n, a| node_left(n) if a == app }
     end
 
     # A node's table app left the network: its members are away at every
@@ -237,8 +238,9 @@ module AsterismGames
     end
 
     def down
-      close_spectate
+      close_room_app
       @net = nil
+      @topics = {}
       @tables_status = nil
       @connected = false
       write_status
@@ -251,7 +253,7 @@ module AsterismGames
     # no nodes, no tokens (the host's own node ID only, once known).
     def status_now(now = @clock.call)
       { "pid" => Process.pid, "at" => Time.now.to_i, "node" => @node, "connected" => @connected ? true : false,
-        "reconnecting" => (@connected && ::Asterism.reconnecting?) ? true : false,
+        "reconnecting" => (@connected && @net&.reconnecting?) ? true : false,
         "tables" => @games.transform_values { |g| g.summary(now) } }.tap do |h|
         h["ai"] = @ai.budget.summary if @ai&.any?
       end
@@ -342,7 +344,7 @@ module AsterismGames
     # Asterism puts them only when they differ from the last put.
     def tell_tables(now, changed: false)
       ts = @tables_status
-      return unless ts && @net && !::Asterism.reconnecting?
+      return unless ts && @net && !@net.reconnecting?
       return unless changed || now - @tables_at.to_i >= TABLES_STATUS_EVERY_MS
       @tables_at = now
       bytes = ts.set(tables_status(now))
@@ -353,28 +355,58 @@ module AsterismGames
 
     def put_state(name, game, now)
       @put_at[name] = now
-      return unless @net && !::Asterism.reconnecting?
-      key = "asterism/#{node}/#{@config['app']}/#{name}/state"
+      return unless @net && !@net.reconnecting?
       # What everybody may see, as a spectator sees it (README "Spectators").
-      payload = ::Asterism::Codec.pack(game.state_view(now))
-      note_size("put #{name}/state", key.bytesize + payload.bytesize)
-      @net.session.put(key, payload)
+      view = game.state_view(now)
+      note_size("put #{name}/state", "asterism/#{node}/#{@config['app']}/#{name}/state".bytesize +
+                                     ::Asterism::Codec.pack(view).bytesize)
+      topic(name, "state").put(view)
     rescue ::Asterism::Error => e
       @log.call("games: put #{name}: #{e.message}")
     end
 
     # What a game told (Game#tell): put on asterism/<node>/<app>/<table>/<sub>.
     def put_told(name, sub, value)
-      return unless @net && !::Asterism.reconnecting?
+      return unless @net && !@net.reconnecting?
       key = "asterism/#{node}/#{@config['app']}/#{name}/#{sub}"
-      payload = ::Asterism::Codec.pack(value)
-      note_size("put #{name}/#{sub}", key.bytesize + payload.bytesize)
+      note_size("put #{name}/#{sub}", key.bytesize + ::Asterism::Codec.pack(value).bytesize)
       @stats["told"] += 1
-      @net.session.put(key, payload)
+      topic(name, sub).put(value)
     rescue ::Asterism::Error => e
       @log.call("games: put #{name}/#{sub}: #{e.message}")
     end
 
+    # ------------------------------------------------------------ topics
+
+    # Connected: the games' types defined on the connection, and every
+    # table's state and told keys declared as topics of this application,
+    # and outside the rooms the tables' spectate keys (the types and the
+    # topics end with the connection).
+    def declare_topics(net)
+      @topics = {}
+      @games.values.map(&:class).uniq.each do |klass|
+        klass::TYPES.each { |tname, (fields, text)| net.define_type(tname, fields, desc: text) }
+      end
+      @games.each do |name, g|
+        topic(name, "state")
+        g.class::TOLD_TYPES.each_key { |sub| topic(name, sub) }
+      end
+      # Outside the rooms the spectate keys are this application's too
+      # (in the node's shared place); a room's go on its own application.
+      declare_spectate(net) unless @config["namespace"]
+    end
+
+    # The topic <table>/<sub> of this connection (declared the first time,
+    # with the game's type for it).
+    def topic(name, sub)
+      @topics ||= {}
+      @topics[[name, sub]] ||= begin
+        klass = @games[name].class
+        type = sub == "state" ? klass::STATE_TYPE : klass::TOLD_TYPES[sub]
+        type ? @net.publish("#{name}/#{sub}", type: type) : @net.publish("#{name}/#{sub}")
+      end
+    end
+
     # ------------------------------------------------------------ spectate
     #
     # What a game gives for those who watch from outside the table
@@ -385,31 +417,45 @@ module AsterismGames
     # ends, the delay is chosen again); a host started again starts with
     # nothing kept. The last one put is put again every PUT_EVERY_MS, so a
     # new subscriber has it within that.
+    #
+    # The keys are in the node's shared place (asterism's docs/protocol.md
+    # 17): asterism/<node>/@shared/spectate/<table>/state, a chunk no
+    # player's role (asterism/*/games/**) and no room reaches. Each is a
+    # topic declared with shared: :node by the application that puts it,
+    # with the game's SPECTATE_TYPE defined on that connection
+    # (Game::SPECTATE_TYPES): outside the rooms the host's own application
+    # (config "app"); in a room, the room's application room<slot>
+    # (room_app), a connection of its own outside the room's namespace.
 
-    # The application chunk of the spectate keys: not the host's app (the
-    # players' role reads asterism/*/<app>/**), and outside every room.
-    SPECTATE_APP = "spectate"
     # What one table keeps for its delay at most (bytes); the oldest goes
     # first (it is then never shown, rather than shown early).
     SPECTATE_KEEP_BYTES = 8 * 1024 * 1024
-    # How often a room's host tries again to open its connection outside
+    # How often a room's host tries again to open its application outside
     # the room (ms).
     SPECTATE_RETRY_MS = 30_000
 
-    # asterism/<node>/spectate/<table>/state; a room's table is
-    # room<slot>-<table> there, so the rooms' tables and the permanent ones
-    # never meet.
-    def spectate_key(name)
+    # The name of a table's spectate topic in the node's shared place:
+    # spectate/<table>/state; a room's table is room<slot>-<table> there,
+    # so the rooms' tables and the permanent ones never meet.
+    def spectate_name(name)
       table = @config["namespace"] ? "#{spectate_label}-#{name}" : name
-      "asterism/#{node}/#{SPECTATE_APP}/#{table}/state"
+      "spectate/#{table}/state"
     end
 
-    # A room's part of its tables' spectate names: the setting (Rooms gives
-    # room<slot>), else the namespace without its slashes.
+    # The whole key: asterism/<node>/@shared/spectate/<table>/state.
+    def spectate_key(name)
+      "asterism/#{node}/@shared/#{spectate_name(name)}"
+    end
+
+    # A room's part of its tables' spectate names, and the name of its
+    # application outside the room: the setting (Rooms gives room<slot>),
+    # else the namespace without its slashes.
     def spectate_label
       @config["spectate_label"] || @config["namespace"].to_s.delete("/")
     end
 
+    alias room_app spectate_label
+
     # Takes what the game gives now (nothing when it gives nil, or the same
     # as last time).
     def take_spectate(name, game, now)
@@ -446,63 +492,161 @@ module AsterismGames
 
     def send_spectate(name, bytes, now)
       @spec[name]["at"] = now
-      sess = spectate_session or return
-      spectate_token(sess)
-      key = spectate_key(name)
       # Counted apart from the players' messages (the hands make it larger).
-      @stats["spectate_max_bytes"] = [@stats["spectate_max_bytes"], key.bytesize + bytes.bytesize].max
-      sess.put(key, bytes)
+      @stats["spectate_max_bytes"] = [@stats["spectate_max_bytes"], spectate_key(name).bytesize + bytes.bytesize].max
+      topic = spectate_topic(name) or return
+      topic.put(::Asterism::Codec.unpack(bytes))
     rescue ::Asterism::Error => e
       @log.call("games: put spectate #{name}: #{e.message}")
     end
 
-    # The application asterism/<node>/spectate on the network (a liveliness
-    # token on the connection that puts), so that the command line and the
-    # MCP bridge take its keys for the values of an application that is
-    # there. Once per connection.
-    def spectate_token(sess)
-      return if @spectate_token_on.equal?(sess) || !sess.respond_to?(:liveliness)
-      @spectate_token_on = sess
-      @spectate_token = sess.liveliness("asterism/#{node}/#{SPECTATE_APP}")
-    rescue ::Asterism::Error => e
-      @log.call("games: spectate: token: #{e.message}")
-    end
-
-    # Where the spectate keys are put: the host's own connection outside
-    # the rooms; in a room a connection of its own without the room's
-    # namespace (open_spectate), when the host joins with its own
-    # certificate (spectate_outside), else nowhere.
-    def spectate_session
-      return nil unless @net && !::Asterism.reconnecting?
-      return @net.session unless @config["namespace"]
-      c = @spectate_conn
-      c && !c.reconnecting? ? c : nil
-    end
-
-    # A room's host opens its connection outside the room (the host's own
-    # certificate, no namespace) once connected, and again after a failure
-    # every SPECTATE_RETRY_MS. Outside the lock: opening waits for the router.
-    def open_spectate(now = @clock.call)
-      return unless @config["namespace"] && @config["spectate_outside"] && @config["credentials"]
-      return if @spectate_conn || now < @spectate_retry_at.to_i
-      return unless @games.values.any? { |g| g.respond_to?(:spectate_view) && g.method(:spectate_view).owner != Game }
-      @spectate_retry_at = now + SPECTATE_RETRY_MS
-      @spectate_conn = ::Asterism::Zenoh.open(locator, credentials: @config["credentials"])
-      @log.call("games: spectate: #{node}/#{SPECTATE_APP} outside #{@config['namespace']} " \
-                "(#{@games.keys.map { |n| spectate_key(n).split('/')[3] }.join(', ')})")
-    rescue ::Asterism::Error, SystemCallError => e
-      @spectate_conn = nil
-      @log.call("games: spectate: cannot connect outside #{@config['namespace']}: #{e.message}; " \
+    # Whether the game puts something for those who watch from outside.
+    def spectates?(game)
+      Host.spectates?(game.class)
+    end
+
+    # Whether a game class gives a spectate view (Game#spectate_view
+    # replaced).
+    def self.spectates?(klass)
+      klass.instance_method(:spectate_view).owner != Game
+    end
+
+    # The connection that puts the spectate keys, when it can put now: the
+    # host's own outside the rooms, the room's application in a room (nil
+    # while it is not open, or with the slot's certificate).
+    def spectate_conn
+      c = @config["namespace"] ? @room : @net
+      c && c.connected? && !c.reconnecting? ? c : nil
+    end
+
+    # The topic spectate/<table>/state of the node's shared place on the
+    # spectate connection (declared the first time, with the game's type
+    # for it), or nil when that connection cannot put now.
+    def spectate_topic(name)
+      conn = spectate_conn or return nil
+      @spectate_topics ||= {}
+      @spectate_topics[name] ||= begin
+        type = @games[name].class::SPECTATE_TYPE
+        type ? conn.publish(spectate_name(name), shared: :node, type: type) : conn.publish(spectate_name(name), shared: :node)
+      end
+    end
+
+    # Declares on conn the spectate types and the topics of the tables
+    # that give a spectate view, and exposes the object that answers their
+    # current values (called when conn is up).
+    def declare_spectate(conn)
+      @spectate_topics = {}
+      spectating = @games.select { |_n, g| spectates?(g) }
+      return if spectating.empty?
+      spectating.values.map(&:class).uniq.each do |klass|
+        klass::SPECTATE_TYPES.each { |tname, (fields, text)| conn.define_type(tname, fields, desc: text) }
+      end
+      spectating.each_key { |name| spectate_topic(name) }
+      expose_spectate(conn)
+    end
+
+    # The object <node>/<app>/spectate of the application that puts the
+    # spectate keys (the host's own outside the rooms, room<slot> in a
+    # room): state(table) answers the value last put on
+    # spectate/<table>/state (README "Spectate"). Asterism's protocol 2
+    # keeps no current value on the network: a reader that comes late, or
+    # missed values (info.lost) or saw the sender start again
+    # (info.restarted?), asks here (the commentary does).
+    SPECTATE_OBJECT = "spectate"
+    SPECTATE_DOC = "The tables watched from outside (README \"Spectate\"): their spectate values."
+    SPECTATE_METHODS = {
+      "state" => { args: ["table"], doc: "The value last put on @shared/spectate/<table>/state (as old as the " \
+                                         "table's spectator delay), or nil when none was put yet." }
+    }.freeze
+
+    def expose_spectate(conn)
+      if @games.key?(SPECTATE_OBJECT)
+        @log.call("games: a table named #{SPECTATE_OBJECT}: its current spectate values are not answered")
+        return
+      end
+      methods = META_DOCS ? SPECTATE_METHODS : { "state" => 1 }
+      extra = META_DOCS ? { doc: SPECTATE_DOC } : {}
+      conn.expose(SPECTATE_OBJECT, SpectateRemote.new(self), methods: methods, **extra)
+    end
+
+    # The value last put on spectate/<table>/state (unpacked), nil when
+    # there is none (no such table, nothing put since the host started).
+    # table: the part of the name under spectate/ (room<slot>-<table> in a
+    # room). Called on a receiving thread, which holds Asterism::LOCK.
+    def spectate_now(table)
+      name = @games.keys.find { |n| spectate_name(n) == "spectate/#{table}/state" } or return nil
+      out = @spec.dig(name, "out") or return nil
+      ::Asterism::Codec.unpack(out)
+    end
+
+    # The exposed spectate object (Host#spectate_now).
+    class SpectateRemote
+      def initialize(host)
+        @host = host
+      end
+
+      def state(table)
+        @host.spectate_now(table.to_s)
+      end
+    end
+
+    # ---- in a room: the room's application outside the room
+    #
+    # Every key a room's host writes on its own connection gets the room's
+    # namespace, which every seat of the room reads. Its tables' spectate
+    # keys go on a second Asterism connection without the namespace, the
+    # application <node>/room<slot> (asterism's docs/protocol.md 1.1: one
+    # application a connection, several in one program), with the host's
+    # own certificate only (the slot's certificate of a console before
+    # 0.3.0 is the room's: spectate_outside false, nothing is put). Its
+    # liveliness token, @profile and @pubs are its own, so every room is
+    # an application of its own beside the permanent tables' games.
+
+    # The room's application, when the host is connected and one of its
+    # games gives a spectate view; opened again after a failure (or a lost
+    # connection) every SPECTATE_RETRY_MS. Outside the lock: opening waits
+    # for the router.
+    def open_room_app(now = @clock.call)
+      # Rooms sets spectate_outside only for the host's own certificate.
+      return unless @config["namespace"] && @config["spectate_outside"]
+      return unless @net && @games.values.any? { |g| spectates?(g) }
+      if @room && !@room.running?
+        @log.call("games: #{node}/#{room_app}: connection lost: #{@room.lost_reason}")
+        close_room_app
+      end
+      return if @room || now < @room_retry_at.to_i
+      @room_retry_at = now + SPECTATE_RETRY_MS
+      opts = { node: node, app: room_app }
+      opts[:credentials] = @config["credentials"] if @config["credentials"]
+      conn = ::Asterism.connect(locator, **opts)
+      begin
+        conn.on_error { |e, where| @log.call("games: #{node}/#{room_app}: #{where}: #{e.class}: #{e.message}") }
+        ::Asterism::LOCK.synchronize { room_up(conn) }
+        conn.start
+      rescue StandardError
+        @room = nil
+        conn.close
+        raise
+      end
+      @log.call("games: #{node}/#{room_app} up outside #{@config['namespace']} " \
+                "(#{@spectate_topics.keys.map { |n| "@shared/#{spectate_name(n)}" }.join(', ')})")
+    rescue ::Asterism::Error, ArgumentError, SystemCallError => e
+      @log.call("games: cannot open #{node}/#{room_app} outside #{@config['namespace']}: #{e.message}; " \
                 "again in #{SPECTATE_RETRY_MS / 1000} s")
     end
 
-    def close_spectate
-      @spectate_token = nil # withdrawn with its connection
-      @spectate_token_on = nil
-      @spectate_retry_at = nil # a new connection tries at once
-      c = @spectate_conn
-      @spectate_conn = nil
-      c&.close
+    # Takes conn as the room's application: its types and topics.
+    def room_up(conn)
+      @room = conn
+      declare_spectate(conn)
+    end
+
+    def close_room_app
+      @room_retry_at = nil # a new connection tries at once
+      app = @room
+      @room = nil
+      @spectate_topics = {}
+      app&.close
     rescue ::Asterism::Error
       nil
     end
@@ -520,33 +664,21 @@ module AsterismGames
       @games.each_value { |g| g.save(now, force: true) }
     end
 
-    # The host's status: Asterism's (net.status, asterism 0.8.0, the
-    # version the Gemfile pins), which puts it when it changes and answers
-    # who asks. An asterism 0.7.1 (the gem's lowest) has no status: then
-    # the same thing by hand on the connection's session (a queryable on
-    # the key and a put when the counts change).
+    # The host's status: Asterism's (net.status), which puts it on
+    # asterism/<node>/<app>/@status when it changes and answers who asks its
+    # profile (@profile?status, asterism's docs/protocol.md 8).
     class TablesStatus
       def initialize(net, node, app)
         @net = net
         @key = "asterism/#{node}/#{app}/@status"
-        return if @net.respond_to?(:status)
-        @bytes = nil
-        @qa = net.session.queryable(@key) { |q| q.reply(@key, @bytes) if @bytes }
       end
 
       # Sets the status; returns the size of the put (key and payload) when
       # it changed, nil when it did not.
       def set(st)
-        bytes = ::Asterism::Codec.pack(st)
-        if @net.respond_to?(:status)
-          return nil if @net.status == st
-          @net.status(st)
-        else
-          return nil if bytes == @bytes
-          @bytes = bytes
-          @net.session.put(@key, bytes)
-        end
-        @key.bytesize + bytes.bytesize
+        return nil if @net.status == st
+        @net.status(st)
+        @key.bytesize + ::Asterism::Codec.pack(st).bytesize
       end
     end
 

data/lib/asterism_games/othello/table.rb

@@ -39,6 +39,18 @@ module AsterismGames
                       "OTHELLO_AI_TURN_SECONDS" => ["ai_turn_ms", 1000] }
 
       SAVE_FORMAT = 1
+      # The state's type (public_view's keys; mb, the members as [name,
+      # seat, flags], an any[]).
+      STATE_TYPE = "#{TYPE_PREFIX}othello.state".freeze
+      TYPES = {
+        STATE_TYPE => [[%w[v int], %w[t str], %w[st str], %w[nm str[]], %w[sk int[]], %w[aw int], %w[ow int],
+                        %w[mb any[]], %w[ts int], %w[ai str[]], %w[ak str[]], %w[bd str], %w[tn int], %w[n int], %w[last str],
+                        %w[lg str], %w[cnt int[]], %w[dl int], ["res", "#{TYPE_PREFIX}othello.result"]],
+                       "An othello table as everybody sees it (asterism-games README \"Views\" of othello); " \
+                       "mb: the members as [name, seat, flags]"],
+        "#{TYPE_PREFIX}othello.result" => [[%w[w int], %w[why str], %w[b int], %w[wc int]],
+                                           "How a game ended: the seat that won (-1 a draw), why, the counts"]
+      }.freeze
       SEATS = 2
       DEFAULTS = AsterismGames::Game::DEFAULTS.merge(
         "turn_ms" => 0,        # a human's time for a move (0: none); then the CPU plays it

data/lib/asterism_games/play/mahjong.rb

@@ -176,9 +176,10 @@ module AsterismGames
         host, app, tname = @path.split("/")
         # The state the host puts after every change: a newer one wakes the
         # ticker (no call waits on the receiving thread).
-        @net.session.subscribe("asterism/#{host}/#{app}/#{tname}/state") do |sample|
-          v = Asterism::Codec.unpack(sample.payload)
-          @wake << true if v.is_a?(Hash) && (!@view.is_a?(Hash) || v["v"] != @view["v"])
+        @net.subscribe("#{host}/#{app}/#{tname}/state") do |v, info|
+          # Values lost, or the host started again (protocol 2 keeps no
+          # current value): the view is asked again whatever this one says.
+          @wake << true if Play.ask_again?(info) || (v.is_a?(Hash) && (!@view.is_a?(Hash) || v["v"] != @view["v"]))
         end
         refresh
         @timer = Thread.new { timer_loop } if @out.tty?

data/lib/asterism_games/play/othello.rb

@@ -106,9 +106,10 @@ module AsterismGames
         # The state the host puts after every change (and every 5 s): a newer
         # one wakes the thread that asks the view (no call waits on the
         # receiving thread).
-        @net.session.subscribe("asterism/#{host}/#{app}/#{tname}/state") do |sample|
-          v = Asterism::Codec.unpack(sample.payload)
-          @wake << true if v.is_a?(Hash) && (@view.nil? || v["v"] != @view["v"])
+        @net.subscribe("#{host}/#{app}/#{tname}/state") do |v, info|
+          # Values lost, or the host started again (protocol 2 keeps no
+          # current value): the view is asked again whatever this one says.
+          @wake << true if Play.ask_again?(info) || (v.is_a?(Hash) && (@view.nil? || v["v"] != @view["v"]))
         end
         refresh
         # And a view every VIEW_EVERY_S anyway: the host sees that this member

data/lib/asterism_games/play.rb

@@ -154,6 +154,15 @@ module AsterismGames
       end
     end
 
+    # Whether a value of a table's state says to ask the table again
+    # (Asterism's protocol 2 keeps no current value on the network): values
+    # were lost before it (info.lost) or the host started a new run
+    # (info.restarted?). The play clients then ask their view at once.
+    def ask_again?(info)
+      return false unless info.respond_to?(:lost)
+      info.lost.to_i.positive? || info.restarted? ? true : false
+    end
+
     # The first table whose name starts with prefix (looking again whenever
     # a node joins, for wait seconds); nil when none.
     def find_tables(net, prefix, joined, wait: 10)

data/lib/asterism_games/rooms.rb

@@ -23,7 +23,8 @@ module AsterismGames
   # for the room, which joins the router in the room's key space
   # (namespace room/<slot>) and serves the tables there, as browsers in the
   # room see them (asterism/games/games/<table>). One process per room,
-  # since the asterism gem keeps one connection a process. Other rooms
+  # since every room's host is the same <node>/<app>, which one program
+  # opens once (the asterism gem refuses a second copy). Other rooms
   # (another app, or an app no configured table's game shows) get nothing.
   #
   # Which certificate (console 0.3.0, its docs/rooms.md "Seats"): when
@@ -264,7 +265,8 @@ module AsterismGames
     # "Rooms", "Who joins"); trust: trust_for's; app: what the room's link
     # opens (its game's tables; nil: every table of rooms.tables); group:
     # its invite link's group (nil: none), kept with its games' records.
-    # spectate_label / spectate_outside: README "Spectate".
+    # spectate_label (the room's application and its tables' spectate
+    # names) / spectate_outside: README "Spectate".
     def child_config(slot, tar, dir, room_id = nil, trust = { "own" => false, "seats" => [], "prefix" => nil }, app = nil,
                      group = nil)
       tables = app ? Config.tables_for_app(@rooms["tables"], app) : @rooms["tables"]
@@ -275,10 +277,11 @@ module AsterismGames
         "trusted_nodes" => trust["seats"], "trusted_prefix" => trust["prefix"],
         "seat_reuse_ms" => @rooms["seat_reuse_seconds"].to_i * 1000, "ai_usage_file" => ai_usage_file,
         "records_db" => records_db, "records_place" => "room", "records_group" => group,
-        # README "Spectate": the tables' spectate keys, outside the room
-        # (asterism/<node>/spectate/room<slot>-<table>/state), put on a
-        # connection without the namespace, with the host's own certificate
-        # only (the slot's certificate of a console before 0.3.0 is the room's).
+        # README "Spectate": the tables' spectate keys in the node's shared
+        # place (asterism/<node>/@shared/spectate/room<slot>-<table>/state),
+        # put by the room's application room<slot> on a connection without
+        # the namespace, with the host's own certificate only (the slot's
+        # certificate of a console before 0.3.0 is the room's).
         "spectate_label" => "room#{slot}", "spectate_outside" => trust["own"] ? true : false }
     end