rgame 0.1.0 → 0.3.0

data/lib/rgame/engine/i18n/plural_rules.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module I18n
+      # CLDR plural categories for whole numbers, one rule per language. A rule
+      # takes the `count` a caller passed and returns one of `Plural::CATEGORIES`.
+      # Every built-in rule answers `:other` for a count that is not an Integer,
+      # because fractional counts have categories of their own that no built-in
+      # table spells out.
+      #
+      # Rules are keyed by language, and `I18n.plural_rule` adds or replaces one;
+      # a language with no rule counts like English.
+      #
+      # Source: the CLDR plural rules, https://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html
+      module PluralRules
+        TWO_TO_FOUR = (2..4)
+        TWELVE_TO_FOURTEEN = (12..14)
+
+        def self.whole(&rule) = ->(count) { count.is_a?(Integer) ? rule.call(count.abs) : :other } # rubocop:disable Performance/RedundantBlockCall -- the rule runs after whole has returned, where yield has no block
+
+        def self.slavic_few?(count) = TWO_TO_FOUR.cover?(count % 10) && !TWELVE_TO_FOURTEEN.cover?(count % 100)
+
+        def self.million(count) = count.positive? && (count % 1_000_000).zero? ? :many : :other
+
+        private_class_method :whole, :slavic_few?, :million
+
+        ONE_OTHER = whole { |n| n == 1 ? :one : :other }
+        ONE_MILLION_OTHER = whole { |n| n == 1 ? :one : million(n) }
+        ZERO_ONE_MILLION_OTHER = whole { |n| n <= 1 ? :one : million(n) }
+
+        EAST_SLAVIC = whole do |n|
+          if n % 10 == 1 && n % 100 != 11 then :one
+          elsif slavic_few?(n) then :few
+          else :many
+          end
+        end
+
+        POLISH = whole do |n|
+          if n == 1 then :one
+          elsif slavic_few?(n) then :few
+          else :many
+          end
+        end
+
+        CZECH = whole do |n|
+          if n == 1 then :one
+          elsif TWO_TO_FOUR.cover?(n) then :few
+          else :other
+          end
+        end
+
+        ARABIC = whole do |n|
+          case n
+          when 0 then :zero
+          when 1 then :one
+          when 2 then :two
+          else
+            case n % 100
+            when 3..10 then :few
+            when 11..99 then :many
+            else :other
+            end
+          end
+        end
+
+        OTHER = ->(_count) { :other }
+
+        BUILT_IN = {
+          en: ONE_OTHER, de: ONE_OTHER, nl: ONE_OTHER, sv: ONE_OTHER, da: ONE_OTHER, nb: ONE_OTHER, fi: ONE_OTHER,
+          it: ONE_MILLION_OTHER, es: ONE_MILLION_OTHER,
+          fr: ZERO_ONE_MILLION_OTHER, pt: ZERO_ONE_MILLION_OTHER,
+          ru: EAST_SLAVIC, uk: EAST_SLAVIC, pl: POLISH, cs: CZECH,
+          ja: OTHER, zh: OTHER, ko: OTHER,
+          ar: ARABIC
+        }.freeze
+
+        DEFAULT = ONE_OTHER
+      end
+    end
+  end
+end

data/lib/rgame/engine/i18n/template.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module I18n
+      # One translated string, compiled once at load: the literal runs and the
+      # `%{name}` placeholders between them, so rendering is an append per part
+      # rather than a parse. `%%{` in the source is a literal `%{`.
+      #
+      # Internal to `I18n`; a game reaches translations through `I18n.t` or a
+      # `Text`, never through a Template.
+      #
+      # @api private
+      class Template
+        PLACEHOLDER = /%%\{|%\{([A-Za-z_]\w*)\}/
+
+        # The variable names the source uses, each once, in order of appearance.
+        attr_reader :names
+
+        def self.compile(source)
+          parts = []
+          literal = +''
+          position = 0
+          while (match = PLACEHOLDER.match(source, position))
+            literal << source[position...match.begin(0)]
+            if match[1]
+              parts << literal.freeze unless literal.empty?
+              parts << match[1].to_sym
+              literal = +''
+            else
+              literal << '%{'
+            end
+            position = match.end(0)
+          end
+          literal << source[position..]
+          parts << literal.freeze unless literal.empty?
+          new(parts)
+        end
+
+        def initialize(parts)
+          @parts = parts.freeze
+          @names = parts.grep(Symbol).uniq.freeze
+          @constant = @names.empty? ? -parts.join : nil
+        end
+
+        # The string with each placeholder replaced by `vars[name].to_s`. A
+        # template without placeholders returns the same frozen String every
+        # time. Every name in `names` must be a key of `vars`.
+        def render(vars)
+          return @constant if @constant
+
+          @parts.each_with_object(+'') do |part, out|
+            out << (part.is_a?(Symbol) ? vars.fetch(part).to_s : part)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/i18n.rb

@@ -1,93 +1,318 @@
 # frozen_string_literal: true
 
 require 'yaml'
+require_relative 'i18n/template'
+require_relative 'i18n/plural'
+require_relative 'i18n/plural_rules'
 
 module RGame
   module Engine
-    # Minimal localization: per-locale translation tables (loaded from YAML or a Hash),
-    # `t(key)` with `%{var}` interpolation and a fallback locale, and a `generation`
-    # counter that ticks whenever the locale changes — so cached UI text knows when to
-    # re-resolve without polling every frame. A global module (like EventDispatcher),
-    # so `t` is reachable anywhere. Pure Ruby; YAML is the only (stdlib) dependency.
+    # Translation tables and the current language, as one global module so a
+    # node can resolve text from its constructor, before it is in any tree.
+    #
+    # Tables are read in Rails' YAML format — the top-level key is the locale,
+    # nested keys below it — and compiled at load into one flat Hash per locale,
+    # keyed by the dotted key, whose values are pre-parsed `%{var}` templates or,
+    # for a key whose nested keys are CLDR plural categories, a set of them.
+    # `generation` moves whenever what a key resolves to may have changed, so
+    # cached text compares one Integer instead of looking anything up.
+    #
+    # `I18n` parses Strings and never opens a file: finding and reading locale
+    # files is the asset manager's job.
     module I18n
+      # Raised for a key no link of the chain has, under `missing = :raise`.
+      class MissingKey < StandardError
+        attr_reader :key, :chain
+
+        def initialize(key, chain)
+          @key = key
+          @chain = chain
+          super("no translation for #{key.inspect} in #{chain.join(', ')}")
+        end
+      end
+
+      # Raised under `missing = :raise` when a `Text` declares other variables
+      # than its translation uses: a placeholder the `Text` does not declare, or
+      # a declared name the translation never prints.
+      class VariableMismatch < StandardError
+        attr_reader :key
+
+        def initialize(key, message)
+          @key = key
+          super("#{key}: #{message}")
+        end
+      end
+
+      MISSING_POLICIES = %i[key raise].freeze
+
       class << self
+        # An Integer that moves on every `load`, every change of locale or
+        # default, every `plural_rule`, and every `reset`.
         attr_reader :generation
 
-        # The locale `t` falls back to when the current locale lacks a key.
-        def default = @fallback
+        attr_reader :locale, :default
+
+        # The locales a key is looked up in, in order: the current locale, each
+        # shorter prefix of it, then the default — `[:'de-AT', :de, :en]`.
+        # Rebuilt when the locale or the default changes, not per lookup.
+        attr_reader :chain
 
+        # What a key no link of the chain has resolves to: `:key` (the start)
+        # shows the key itself, `:raise` raises `MissingKey`, and a callable is
+        # called with the key and the chain and its return value is shown.
+        attr_reader :missing
+
+        # Merges a YAML document in Rails' format into the loaded tables. One
+        # document may hold several locales, and a locale loaded twice is merged
+        # key by key rather than replaced. `source` names the file in errors.
+        def load(yaml, source: nil)
+          merge(YAML.safe_load(yaml, aliases: true, filename: source), source || 'translations')
+        end
+
+        # `load` for a Hash already in memory: `load_hash(en: { menu: { title: 'Menu' } })`.
+        def load_hash(hash) = merge(hash, 'translations')
+
+        # Switches the language. `de_AT`, `'de-at'` and `:'de-AT'` name the same
+        # locale. A locale with no table of its own is allowed and resolves
+        # through its chain, so `:'de-CH'` reads the `de` table.
+        def locale=(locale)
+          locale = normalize(locale)
+          return if locale == @locale
+
+          @locale = locale
+          relink
+        end
+
+        # The last link of every chain, and the locale `choose` falls back to.
         def default=(locale)
-          @fallback = locale.to_sym
+          locale = normalize(locale)
+          return if locale == @default
+
+          @default = locale
+          relink
         end
 
-        def reset
-          @locales = {}
-          @current = :en
-          @fallback = :en
-          @generation = 0
+        # The canonical Symbol for a locale identifier: the language lowercase,
+        # a region uppercase, a script capitalized, joined by hyphens —
+        # `normalize('zh_hant_tw') # => :'zh-Hant-TW'`.
+        def normalize(locale)
+          language, *subtags = locale.to_s.split(/[-_]/)
+          raise ArgumentError, "not a locale: #{locale.inspect}" if language.nil? || language.empty?
+
+          subtags.map! { |subtag| subtag.length == 4 ? subtag.capitalize : subtag.upcase }
+          subtags.unshift(language.downcase).join('-').to_sym
         end
 
-        # Register a locale's translations (nested Hashes allowed). Keys are symbolized
-        # so YAML ("string keys") and inline symbol keys look the same to `t`.
-        def load(locale, translations)
-          @locales[locale.to_sym] = symbolize(translations)
-          self
+        # The first of `preferred` — the player's languages, most wanted first —
+        # that has a table for itself or a shorter prefix of itself, normalized
+        # but not shortened: `choose(['fr-CA', 'de-AT'])` with a `de` table is
+        # `:'de-AT'`. The default when none has.
+        def choose(preferred)
+          preferred.each do |candidate|
+            locale = normalize(candidate)
+            return locale if lineage(locale).any? { |link| @tables.key?(link) }
+          end
+          @default
         end
 
-        def load_file(locale, path)
-          load(locale, YAML.load_file(path))
+        def missing=(policy)
+          unless MISSING_POLICIES.include?(policy) || policy.respond_to?(:call)
+            raise ArgumentError, "missing must be :key, :raise or a callable, not #{policy.inspect}"
+          end
+
+          @missing = policy
         end
 
-        def locale = @current
+        # The keys the default locale has that no table in `locale`'s own chain
+        # does, in the default table's order. A key `locale` gets from a parent
+        # (`de-AT` from `de`) is not missing; one it would get only from the
+        # default is.
+        def missing_keys(locale)
+          links = lineage(normalize(locale))
+          defaults = @tables.fetch(@default, {}).keys
+          defaults.reject { |key| links.any? { |link| @tables[link]&.key?(key) } }
+        end
 
-        # Switching the locale bumps the generation so observers re-resolve their text.
-        def locale=(locale)
-          locale = locale.to_sym
-          return if locale == @current
+        # Sets how `language` (or a regional locale, which then wins over its
+        # language) sorts a count into a plural category. The block receives
+        # the count and returns one of `Plural::CATEGORIES`. Replaces a built-in
+        # rule; lasts until `reset`.
+        def plural_rule(language, &rule)
+          raise ArgumentError, 'plural_rule needs a block' unless rule
 
-          @current = locale
+          @plural_rules[normalize(language)] = rule
+          @rule_for.clear
           @generation += 1
+          self
         end
 
-        def available = @locales.keys
+        # The locales that have a table, in load order.
+        def available = @tables.keys
 
-        # Resolve a dotted key ("menu.title" or :menu_title) in the current locale, then
-        # the fallback locale, then the key itself; interpolate %{var} from `vars`.
-        #
-        # Pass `count:` to pluralize: the key's value is then a table of forms
-        # ({ one:, other:, optionally zero: }), and `count` is also exposed to
-        # interpolation as %{count}. English/German use the one/other rule.
-        def t(key, count: nil, **vars)
-          value = lookup(@current, key) || lookup(@fallback, key)
-          value = pluralize(value, count) if count && value.is_a?(Hash)
-          return key.to_s unless value.is_a?(String)
+        # The translation of `key` (or `scope.key`) with `vars` interpolated. A
+        # pluralized key needs `count:`, and picks its form by the plural rule
+        # of the table that supplied it, which is not always the current locale.
+        # Allocates on every call: it is for code off the per-frame path.
+        def t(key, scope: nil, **vars)
+          key = scope ? "#{scope}.#{key}" : key.to_s
+          template = lookup(key)
+          return answer_missing(key) unless template
 
-          vars = vars.merge(count: count) if count
-          vars.empty? ? value : (value % vars)
+          template = pluralize(key, template, vars) if template.is_a?(Plural)
+
+          missing = template.names.find { |name| !vars.key?(name) }
+          raise ArgumentError, "#{key} needs %{#{missing}}" if missing
+
+          template.render(vars)
+        end
+
+        # What a `Text` declaring `names` shows for the dotted `key`, with `vars`
+        # — a Hash holding exactly those names — interpolated. It differs from
+        # `t` in one way: a translation whose placeholders are not the declared
+        # names is a bug in the table or the code, and the missing policy
+        # answers it, raising `VariableMismatch` under `:raise`.
+        def render(key, names, vars)
+          entry = lookup(key)
+          return answer_missing(key) unless entry
+
+          problem = mismatch(entry, names)
+          return answer_mismatch(key, problem) if problem
+
+          entry = pluralize(key, entry, vars) if entry.is_a?(Plural)
+          entry.render(vars)
+        end
+
+        # Forgets every table and plural rule added, and restores the starting
+        # locale and default, `:en`, and the `:key` missing policy. The
+        # generation moves rather than restarting, so text cached before a
+        # reset never mistakes itself for current.
+        def reset
+          @tables = {}
+          @sources = {}
+          @locale = :en
+          @default = :en
+          @generation = (@generation || 0) + 1
+          @chain = chain_for(@locale)
+          @plural_rules = PluralRules::BUILT_IN.dup
+          @rule_for = {}
+          @missing = :key
         end
 
         private
 
-        def pluralize(forms, count)
-          return forms[:zero] if count.zero? && forms.key?(:zero)
+        def relink
+          @chain = chain_for(@locale)
+          @generation += 1
+        end
+
+        def chain_for(locale) = (lineage(locale) << @default).uniq.freeze
+
+        def lineage(locale)
+          subtags = locale.name.split('-')
+          subtags.size.downto(1).map { |length| subtags.first(length).join('-').to_sym }
+        end
+
+        def answer_missing(key)
+          case @missing
+          when :key then key
+          when :raise then raise MissingKey.new(key, @chain)
+          else @missing.call(key, @chain)
+          end
+        end
+
+        def mismatch(entry, names)
+          undeclared = entry.names.find { |name| !names.include?(name) }
+          if undeclared == :count && entry.is_a?(Plural)
+            'is pluralized, and the Text does not declare :count'
+          elsif undeclared
+            "uses %{#{undeclared}}, which the Text does not declare"
+          elsif (unused = names.find { |name| !entry.names.include?(name) })
+            "never uses :#{unused}, which the Text declares"
+          end
+        end
+
+        def answer_mismatch(key, problem)
+          case @missing
+          when :key then key
+          when :raise then raise VariableMismatch.new(key, problem)
+          else @missing.call(key, @chain)
+          end
+        end
+
+        def pluralize(key, plural, vars)
+          raise ArgumentError, "#{key} is pluralized and needs count:" unless vars.key?(:count)
+
+          count = vars[:count]
+          plural.template_for(count, plural_category(plural.locale, count))
+        end
+
+        def plural_category(locale, count)
+          rule = @rule_for[locale] ||= begin
+            language = lineage(locale).find { |link| @plural_rules.key?(link) }
+            @plural_rules.fetch(language, PluralRules::DEFAULT)
+          end
+          rule.call(count)
+        end
 
-          forms[count == 1 ? :one : :other] || forms[:other]
+        def lookup(key)
+          @chain.each do |link|
+            entry = @tables[link]&.[](key)
+            return entry if entry
+          end
+          nil
         end
 
-        def lookup(locale, key)
-          node = @locales[locale]
-          key.to_s.split('.').each do |segment|
-            return nil unless node.is_a?(Hash)
+        def merge(hash, source)
+          raise ArgumentError, "#{source}: expected a Hash of locales" unless hash.is_a?(Hash)
+
+          hash.each do |locale, entries|
+            raise ArgumentError, "#{source}: #{locale} must hold a Hash of keys" unless entries.is_a?(Hash)
+
+            locale = normalize(locale)
+            @sources[locale] = deep_merge(@sources.fetch(locale, {}), stringify(entries, locale.to_s, source))
+            @tables[locale] = compile(@sources[locale], locale)
+          end
+          @generation += 1
+          self
+        end
 
-            node = node[segment.to_sym]
+        def stringify(entries, path, source)
+          entries.to_h do |name, value|
+            name = scalar_name(name, path, source)
+            here = "#{path}.#{name}"
+            [name, value.is_a?(Hash) ? stringify(value, here, source) : scalar_value(value, here, source)]
           end
-          node
         end
 
-        def symbolize(value)
-          return value unless value.is_a?(Hash)
+        def scalar_name(name, path, source)
+          return name.to_s if name.is_a?(String) || name.is_a?(Symbol) || name.is_a?(Integer)
 
-          value.to_h { |k, v| [k.to_sym, symbolize(v)] }
+          raise ArgumentError, "#{source}: #{path} has the key #{name.inspect}; " \
+                               'YAML reads yes/no/on/off/true/false/~ unquoted, so quote it'
+        end
+
+        def scalar_value(value, path, source)
+          return value.to_s if value.is_a?(String) || value.is_a?(Numeric)
+
+          raise ArgumentError, "#{source}: #{path} is #{value.inspect}, not text; " \
+                               'quote it if it is meant as a string'
+        end
+
+        def deep_merge(into, from)
+          into.merge(from) do |_name, old, new|
+            old.is_a?(Hash) && new.is_a?(Hash) ? deep_merge(old, new) : new
+          end
+        end
+
+        def compile(entries, locale, prefix = nil, table = {})
+          entries.each do |name, value|
+            key = prefix ? "#{prefix}.#{name}" : name
+            if !value.is_a?(Hash) then table[key.freeze] = Template.compile(value)
+            elsif Plural.forms?(value) then table[key.freeze] = Plural.new(locale, value)
+            else compile(value, locale, key, table)
+            end
+          end
+          prefix ? table : table.freeze
         end
       end
 

data/lib/rgame/engine/input/action_mapper.rb

@@ -2,45 +2,99 @@
 
 module RGame
   module Engine
-    # Polls an InputBackend through a binding map and produces an Actions snapshot.
-    # The map is `{ action_name => { axis: %i[neg pos] } | { button: %i[ids] } }`;
-    # physical ids are decoupled from any backend's constants (the backend resolves
-    # them), so remapping is just swapping this data.
+    # Polls one player's device through an InputMap and produces their Actions
+    # snapshot.
     #
-    # Pure logic: the backend is duck-typed — the whole interface is
-    # `down?(physical_id)` — so a test passes a fake and a game passes
-    # `RGame::Core::Input`.
+    #   mapper = ActionMapper.new(input_map, device: Controls.gamepad(0))
+    #   actions = mapper.poll(input)
+    #
+    # **One of these per player.** The device is what makes that work: every
+    # query carries it, so two mappers over the same map read two different
+    # controllers, and each keeps its own previous-frame state so their edge
+    # queries are independent.
+    #
+    # Pure logic. The backend is duck-typed and the whole interface is
+    # `down?(physical_id, device:)` and `axis(axis_id, device:)` — a spec passes
+    # a fake and a game passes RGame::Core::Input.
     class ActionMapper
-      attr_accessor :map
+      DEAD_ZONE = 0.15
+
+      attr_reader :map, :actions
+      attr_accessor :device, :dead_zone
 
-      def initialize(map)
+      def initialize(map, device: RGame::Util::Controls::KEYBOARD, dead_zone: DEAD_ZONE)
         @map = map
-        # One reusable snapshot: there's exactly one input state per tick, so we
-        # mutate these in place each poll instead of allocating (after the first
-        # poll warms the hash keys, steady-state polling allocates nothing).
-        # `@prev_held` carries last frame's button state so Actions can answer edge
-        # queries (pressed?/released?).
+        @device = device
+        @dead_zone = dead_zone
+
         @held = {}
         @prev_held = {}
         @axes = {}
+        map.bindings.each_key do |name|
+          @held[name] = false
+          @prev_held[name] = false
+          @axes[name] = 0.0
+        end
         @actions = Actions.new(held: @held, axes: @axes, prev_held: @prev_held)
       end
 
       def poll(backend)
-        # Snapshot this frame's held state as "previous" before recomputing it
-        # (in-place copy: no allocation once the keys exist).
         @held.each { |name, down| @prev_held[name] = down }
 
-        @map.each do |name, binding|
-          if (axis = binding[:axis])
-            neg, pos = axis
-            @axes[name] = (backend.down?(pos) ? 1.0 : 0.0) - (backend.down?(neg) ? 1.0 : 0.0)
-          end
-          @held[name] = binding[:button].any? { |b| backend.down?(b) } if binding[:button]
+        return rest if @device.nil?
+
+        @map.bindings.each do |name, binding|
+          @held[name] = any_down?(backend, binding.buttons) if binding.buttons
+          @axes[name] = axis_value(backend, binding) if binding.pairs || binding.stick
         end
 
         @actions
       end
+
+      private
+
+      def rest
+        @held.each_key { |name| @held[name] = false }
+        @axes.each_key { |name| @axes[name] = 0.0 }
+        @actions
+      end
+
+      # hot-path
+      def any_down?(backend, ids)
+        ids.any? { |id| backend.down?(id, device: @device) }
+      end
+
+      # hot-path
+      def axis_value(backend, binding)
+        digital = digital_axis(backend, binding)
+        return digital unless binding.stick
+
+        analog = dead_zoned(backend.axis(binding.stick, device: @device))
+        digital.abs >= analog.abs ? digital : analog
+      end
+
+      # hot-path
+      def digital_axis(backend, binding)
+        pairs = binding.pairs
+        return 0.0 if pairs.nil?
+
+        best = 0.0
+        pairs.each do |pair|
+          value = (backend.down?(pair[1], device: @device) ? 1.0 : 0.0) -
+                  (backend.down?(pair[0], device: @device) ? 1.0 : 0.0)
+          best = value if value.abs > best.abs
+        end
+        best
+      end
+
+      # hot-path
+      def dead_zoned(value)
+        magnitude = value.abs
+        return 0.0 if magnitude <= @dead_zone
+
+        scaled = (magnitude - @dead_zone) / (1.0 - @dead_zone)
+        value.negative? ? -scaled : scaled
+      end
     end
   end
 end