asterism-games 0.17.1 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74d2dd1c8e013edfbce9943fa6a725a5173f5acfdaabbc42d93907759fd287b4
-  data.tar.gz: e8325208b814ef8e5e7a1d98286c828c287977f8698f1ccf049fd8a6917a4a04
+  metadata.gz: 8555b735e1a25aff6167fe382f450dd367c4c6d81d13497c932265cf3a61a5f4
+  data.tar.gz: 5185c71e72d56963cebb26d480bf647763dd51156a0285db1104f6a9f600ae22
 SHA512:
-  metadata.gz: 36982adb8c6655a83e6f5a007647f1fa814ad9719d6d4f92ceebee2e18131c5297b42576c24692ed8e388afa42f8a62b186a264bd1bec7a2d696565f5f03d74c
-  data.tar.gz: 2102d3e914d962b470008e8ffce3b8d4366243aa5962b0b124f91e5fbdf993cd36e49e97af735c8f861e412465ac3d0af8b93c777ae5c3133e3b4356d1d3d48d
+  metadata.gz: 48a9fc1196c4f3fb5b2b2b8cf8c9f3c4f0682a4b1beee018ec0518c2c131068c5113ccb309d008f97a8ce479dd2ba994a2e268b5bcd50869bca5ee692144a030
+  data.tar.gz: 8227908a95b02825a6e53ba1c1d75d9008f33b802fca25c82b41c03b0194b3d58e3f7c317ab3e6df7f770140b9a34410467ec3c0ea0a2be189ddc56ffdabca5b

data/CHANGELOG.md

@@ -3,6 +3,33 @@
 Versions before 0.11.1 are noted in the README where each feature is
 described ("games 0.10.0" and the like).
 
+## 0.18.0
+
+- **Spectate** (README "Spectate"): the host puts a table's spectate view
+  on `asterism/<node>/spectate/<table>/state` (a room's table as
+  `room<slot>-<table>`), a key outside the players' role
+  (`asterism/*/games/**`) and outside every room, for a console's
+  spectators and viewers and for the asterism gem's command line and MCP
+  bridge. The framework's `Game#spectate_view` (nil by default: nothing
+  is put) and `Game#spectate_delay_ms`; the host takes the view when it
+  puts the state, keeps it for the delay and puts each one in order, and
+  puts the last one again every 5 s. A room's host puts its tables' views
+  on a second connection of its own (the host's own certificate, no
+  namespace), never into the room; with a slot's certificate (a console
+  before 0.3.0) nothing. The application `spectate` is on the network (a
+  liveliness token) while the host puts.
+- The mahjong table's spectate view: the table in words as `look` gives
+  it, with every seat's hand and drawn tile (the hands a spectator member
+  sees); never the wall, the ura dora, an indicator not turned yet, a node
+  or a token. Held for the table's spectator delay (none by default).
+  Othello and the drawing board put nothing.
+- The console's role `games-host` needs two more lines for it (Read and
+  write `asterism/${node}/spectate`, `asterism/${node}/spectate/**`); the
+  console's docs/rooms.md has them and the `spectator` role. Without them
+  the router drops the puts and nothing else changes.
+- The host's last log line counts the spectate puts and their largest
+  size apart from the players' messages.
+
 ## 0.17.1
 
 - `bin/othello-tty` is gone: `asterism-games play othello` is the same

data/README.md

@@ -512,6 +512,84 @@ the host offers: its money of the day (`usd`), the limit it stops at
 - **Size.** Five tables take about 300 bytes (the largest put is in the
   log's `largest message` with the others).
 
+## Spectate
+
+A table can also be watched from outside it, with what the players do not
+see of each other (games 0.18.0): the host puts a game's spectate view on
+a key no player's role reads and no room reaches, for an admin, a
+spectator's row of the console, or an AI assistant that only looks (the
+asterism gem's command line and MCP bridge). The mahjong table puts the
+four hands there; othello and the drawing board put nothing (they hide
+nothing: their state is the whole game).
+
+- **The key.** `asterism/<node>/spectate/<table>/state`: the host's node,
+  the application `spectate` (not the host's `games`, so the players' role
+  `asterism/*/games/**` does not match it), and the table. A room's table
+  is `room<slot>-<table>` there (`asterism/games/spectate/room01-mahjong1/state`),
+  so the rooms' tables and the permanent ones never meet. The value is
+  MessagePack, like the state.
+- **Outside the rooms.** Every key a room's host writes on its own
+  connection gets the room's namespace (`room/<slot>/...`), which every
+  seat of the room reads whole. So a room's host opens a second connection
+  of its own for the spectate keys, with its own certificate and without
+  the namespace: the key is then on the registered side, where the seats'
+  rules do not reach. It does so only with the host's own certificate (a
+  console from 0.3.0 lists the host in `rooms.json`'s `"hosts"`); with the
+  slot's certificate of an older console it puts nothing (that
+  certificate is the room's). The permanent tables' host and a host of its
+  own put on their one connection.
+- **What the mahjong table puts.** The table in words, as `look` gives it
+  ("Playing from a program") to a member without a seat, with each seat's
+  `hand` and `drawn` tile, the same four hands a spectator member's view
+  has (`sh`, `sd`): the seats (name, kind, wind, score, riichi, river,
+  melds, hand count, hand, drawn), the round (wind, number, honba, riichi
+  sticks, dealer, wall left, turn, phase), the dora indicators turned so
+  far, the last discard, the result and the final ranks, the rules, and
+  `delay_s`. Never the wall, the ura dora, an indicator not turned yet, a
+  member's node or token (`test/test_spectate.rb` looks for them):
+
+  ```
+  games/spectate/mahjong1/state
+  {"table":"mahjong1","status":"play","sv":212,
+   "seats":[{"seat":0,"name":"CPU1","kind":"cpu","score":21000,"wind":"north","riichi":false,
+             "river":["2z","4z","5z","1m",...],"melds":[{"type":"pon","tiles":["7z","7z","7z"],"from":1}],
+             "hand_count":10,"hand":["7m","7m","2p","3p","3p","4p","4p","5s","6s","7s"],"drawn":null}, ...],
+   "round":{"wind":"east","number":2,"honba":0,"riichi_sticks":1,"dealer":1,"wall_left":19,"turn":3,"phase":"discard"},
+   "dora_indicators":["9p"],"last_discard":{...},"rules":{...},"delay_s":0}
+  ```
+- **The delay.** The table's spectator delay ("Spectators": the setting
+  `spectator_delay_minutes`, or the owner's choice in the lobby; none by
+  default). The host takes the view when it puts the state (after a change,
+  and every 5 s), keeps each one in order and puts it once it is the delay
+  old, each in turn: what is put is what the table was the delay ago,
+  never sooner, also across a round's end or when the delay is chosen
+  again (a shorter delay lets out what is old enough at once). A host
+  started again starts with nothing kept (nothing is put for the delay).
+  At most 8 MB is kept per table; past that the oldest is dropped (never
+  shown rather than shown early). The last one put is put again every
+  5 s, so a new subscriber has it within that.
+- **Who reads it.** The console's docs/rooms.md, "Watching the tables
+  from outside": the host's role `games-host` needs
+  `asterism/${node}/spectate` and `asterism/${node}/spectate/**` in "Read
+  and write" (without them the router drops the puts, and nothing else
+  changes); a role `spectator` (Read `asterism/*/spectate` and
+  `asterism/*/spectate/**`, Watch `asterism/**`) reads them with the
+  command line, and the `viewer` role (Read `asterism/**`) with the
+  command line and the MCP bridge. The players' role `games` and the
+  rooms' seats do not reach them.
+- **Looking.** With the asterism gem's command line (asterism 0.10.0's
+  `object` commands): `asterism object echo 'games/spectate/*' --credentials
+  spectator.tar` (each put as it comes; `-o json` a line each), `asterism
+  object get games/spectate/mahjong1 --credentials viewer.tar` (the next
+  one). The MCP bridge (`asterism mcp --credentials viewer.tar`):
+  `asterism_values` with the pattern `games/spectate/*/state`. The bridge
+  subscribes to `asterism/**`, which a `spectator` row may not, so it
+  needs the viewer role. The host's application `spectate` is on the
+  network (a liveliness token) while it puts, so the values show as an
+  application that is there.
+- **Writing a game.** `spectate_view(now)` (nil, the default: nothing) and
+  `spectate_delay_ms` (0) of `AsterismGames::Game`.
+
 ## Writing a game
 
 A game is two classes on the framework: the table (`AsterismGames::Game`:
@@ -591,6 +669,7 @@ What the framework gives a game:
 | `changed`, `dirty?`, `unsaved?` | a change to save and put; a change only one member's view shows (`@unsaved = true`) is saved, not put |
 | `to_saved` / `restore` / `resume_clock`, `SAVE_FORMAT` | the saved form (one JSON file per table, `state_dir/<table>.json`, written to a temporary file and renamed); a state of another format is not read. Times are saved as the time left and resumed with the host's clock |
 | `tell(sub, value)`, `SAVE_HOLD_MS` | more than the state: the host puts `value` on `asterism/<node>/<app>/<table>/<sub>` on its next step, in the order told, before the state (the board's strokes). A game that changes many times a second writes its saved state at most once per `SAVE_HOLD_MS` (the host writes what is held when it stops) |
+| `spectate_view(now)`, `spectate_delay_ms` | what the host puts on `asterism/<node>/spectate/<table>/state` for those who watch from outside the table ("Spectate"), held for the delay; nil (the default): nothing. It may hold what the players do not see of each other, never what nobody knows yet |
 | `summary(now)` | the counts the status shows (`st`, `members`, `humans`, `cpus`, `away`, and the game's own): no names, no nodes, no tokens. `busy` (`bin/asterism-games status --idle`) is `humans - away` |
 | `settings`, `tables`, `screens`, `DEFAULTS` | the table keys of the settings file and the environment, the tables a host serves by default, the table apps that get the tables in a room, the table's options |
 
@@ -758,6 +837,10 @@ hand.
   CPU) or every 20 s (a person) does not change how far behind the
   spectators are. A host started again starts the delay over (the past is
   not saved).
+- **From outside the table.** The same four hands, in words and as old
+  as the spectators' view, go on `asterism/<node>/spectate/<table>/state`
+  for a console's spectators and viewers ("Spectate"), a key the players
+  cannot read.
 - **The default is no delay.** The spectators see the hands as they are:
   good for watching a game, and for an audience in the same room. A seated
   player who joins the same table from a second screen sees the others'
@@ -1818,6 +1901,13 @@ ASTERISM_TEST_ROUTER=tcp/127.0.0.1:7447 bundle exec rake test   # also through a
   tonpuu game against three CPUs each to the end from scripted input
   (letters, tiles, calls, passes, OKs; `PLAY_TRANSCRIPT_DIR` keeps what
   they showed).
+- `test_spectate.rb`: the spectate view (README "Spectate"; its
+  framework part in `rake test:gem` too): nothing by default (othello, the
+  board), the keys of the permanent tables and of a room, what the rooms
+  give their hosts, the mahjong view (the four hands, no token, node, wall
+  or ura dora), a CPU game on the host, the delay (0, and 3 s across a
+  round's end, in order, never sooner), a room's table on the connection
+  outside the room only, and the last put again after 5 s.
 - `test_play_commands.rb`: `--commands "sit,cpu,start"` against a table
   in this process: they wait for the lobby when a game is going on as
   the client joins (and then sit, fill and start), the owner's wait for

data/VERSION

@@ -1 +1 @@
-0.17.1
+0.18.0

data/lib/asterism_games/game.rb

@@ -38,7 +38,9 @@ module AsterismGames
   #                          (the board's strokes) holds its writes
   #
   # and writes the rules: tick(now), public_view(now) (and spectator_view,
-  # summary when they differ), to_saved(now) / restore(data, now) and the
+  # summary when they differ; spectate_view and spectate_delay_ms for what
+  # the host puts outside the players' keys, README "Spectate"),
+  # to_saved(now) / restore(data, now) and the
   # methods its Remote calls. A game that hands out more than its state
   # (the board's strokes) tells it with tell(sub, value): the host puts
   # value on asterism/<node>/<app>/<table>/<sub>, in the order told, on its
@@ -153,6 +155,22 @@ module AsterismGames
       spectator_view(now)
     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
+    # 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
+    # yet (a wall) nor a token. nil (the default): nothing is put.
+    def spectate_view(_now)
+      nil
+    end
+
+    # How old what spectate_view gives is when the host puts it (ms; 0: at
+    # once). A game with a spectator delay gives it here.
+    def spectate_delay_ms
+      0
+    end
+
     # Counts for the host's status (GET /status of the rooms' host, README
     # "Rooms"): no names, no nodes, no tokens. "st" (the game's status),
     # "members", "humans" (members in a seat), "cpus", "away" (humans not

data/lib/asterism_games/host.rb

@@ -52,6 +52,7 @@ module AsterismGames
       @methods = {}
       @docs = {}
       @put_at = {}
+      @spec = {} # table => {"q" => [[ms, bytes], ...], "bytes", "last", "out", "at"} (README "Spectate")
       @stats = Hash.new(0)
       config["tables"].each do |t|
         klass = AsterismGames.game(t["game"]) or raise ArgumentError, "unknown game #{t['game'].inspect}"
@@ -132,7 +133,8 @@ module AsterismGames
       end
       save_all
       @ai&.stop
-      @log.call("games: largest message #{@stats['max_bytes']} B (#{@stats['max_what']})")
+      @log.call("games: largest message #{@stats['max_bytes']} B (#{@stats['max_what']})" \
+                "#{"; spectate #{@stats['spectate']} puts, at most #{@stats['spectate_max_bytes']} B" if @stats['spectate'].positive?}")
       if @ai&.any?
         n, avg, max = @ai.times
         @log.call("games: AI players: #{@ai.stats.to_h.inspect}; #{n} decisions, #{avg} ms on average, #{max} ms at most; " \
@@ -195,6 +197,7 @@ module AsterismGames
           @log.call("games: connection lost: #{net.lost_reason}")
           return
         end
+        open_spectate
         ::Asterism::LOCK.synchronize { step }
         sleep LOOP_S
       end
@@ -234,6 +237,7 @@ module AsterismGames
     end
 
     def down
+      close_spectate
       @net = nil
       @tables_status = nil
       @connected = false
@@ -277,12 +281,15 @@ module AsterismGames
           changed = true
           g.save(now)
           put_state(name, g, now)
+          take_spectate(name, g, now)
         elsif g.unsaved?
           # A change only one member's own view shows: saved, not put.
           g.save(now)
         elsif now - @put_at.fetch(name, 0) >= PUT_EVERY_MS
           put_state(name, g, now)
+          take_spectate(name, g, now)
         end
+        put_spectate(name, g, now)
       end
       write_status(now) if @config["status_file"] && now - @status_at.to_i >= STATUS_EVERY_MS
       tell_tables(now, changed: changed)
@@ -368,6 +375,138 @@ module AsterismGames
       @log.call("games: put #{name}/#{sub}: #{e.message}")
     end
 
+    # ------------------------------------------------------------ spectate
+    #
+    # What a game gives for those who watch from outside the table
+    # (Game#spectate_view, README "Spectate"): taken when the state is put
+    # (a change, and every PUT_EVERY_MS), kept in order and put once it is
+    # Game#spectate_delay_ms old, each in turn, on spectate_key. Nothing is
+    # put sooner than the delay asks, whatever happens between (a round
+    # 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 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
+    # 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)
+      table = @config["namespace"] ? "#{spectate_label}-#{name}" : name
+      "asterism/#{node}/#{SPECTATE_APP}/#{table}/state"
+    end
+
+    # A room's part of its tables' spectate names: the setting (Rooms gives
+    # room<slot>), else the namespace without its slashes.
+    def spectate_label
+      @config["spectate_label"] || @config["namespace"].to_s.delete("/")
+    end
+
+    # Takes what the game gives now (nothing when it gives nil, or the same
+    # as last time).
+    def take_spectate(name, game, now)
+      v = game.spectate_view(now)
+      return if v.nil?
+      bytes = ::Asterism::Codec.pack(v)
+      s = (@spec[name] ||= { "q" => [], "bytes" => 0 })
+      return if bytes == s["last"]
+      s["last"] = bytes
+      s["q"] << [now, bytes]
+      s["bytes"] += bytes.bytesize
+      while s["bytes"] > SPECTATE_KEEP_BYTES && s["q"].size > 1
+        s["bytes"] -= s["q"].shift[1].bytesize
+        @stats["spectate_dropped"] += 1
+      end
+    end
+
+    # Puts what is old enough now, in order; or the last one again.
+    def put_spectate(name, game, now)
+      s = @spec[name] or return
+      q = s["q"]
+      unless q.empty?
+        delay = game.spectate_delay_ms.to_i
+        while q.first && q.first[0] <= now - delay
+          bytes = q.shift[1]
+          s["bytes"] -= bytes.bytesize
+          s["out"] = bytes
+          send_spectate(name, bytes, now)
+          @stats["spectate"] += 1
+        end
+      end
+      send_spectate(name, s["out"], now) if s["out"] && now - s["at"].to_i >= PUT_EVERY_MS
+    end
+
+    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)
+    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}; " \
+                "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
+    rescue ::Asterism::Error
+      nil
+    end
+
     # The largest message seen so far, key and payload together.
     def note_size(what, bytes)
       return unless bytes > @stats["max_bytes"]

data/lib/asterism_games/rooms.rb

@@ -264,6 +264,7 @@ 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".
     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"]
@@ -273,7 +274,12 @@ module AsterismGames
         "status_file" => File.join(dir, "host.json"), "tables" => tables, "room_id" => room_id,
         "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 }
+        "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).
+        "spectate_label" => "room#{slot}", "spectate_outside" => trust["own"] ? true : false }
     end
 
     # What the AI players cost, shared by every host process (README "AI

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: asterism-games
 version: !ruby/object:Gem::Version
-  version: 0.17.1
+  version: 0.18.0
 platform: ruby
 authors:
 - Katsuhiko Kageyama
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-10-19 00:00:00.000000000 Z
+date: 2026-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: asterism