dr_talon 0.1.0

data/lib/dr_talon/project.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module DrTalon
+  # A DragonRuby game (or library) directory managed by talon.
+  #
+  # Two layouts are supported:
+  # - +:full+, DragonRuby's own: engine files at the root, game in +mygame/+
+  # - +:game_only+: the root is the game directory (+app/main.rb+), as used
+  #   by libraries; only the engine binary and font sit beside it
+  class Project
+    PIN_FILE = ".dragonruby-version"
+
+    # No project at or above the working directory.
+    class NotFound < Error; end
+
+    # Walks up from +dir+ to the nearest directory with a {PIN_FILE}.
+    #
+    # @param dir [String]
+    # @return [Project, nil]
+    def self.find(dir = Dir.pwd)
+      dir = File.expand_path(dir)
+
+      loop do
+        return new(dir) if File.file?(File.join(dir, PIN_FILE))
+
+        parent = File.dirname(dir)
+        return nil if parent == dir
+
+        dir = parent
+      end
+    end
+
+    # The pinned project at or above +dir+, or else +dir+ itself when it
+    # looks like a DragonRuby game. Refuses other directories so engine files
+    # never get copied somewhere unexpected, such as a home directory.
+    #
+    # @param dir [String]
+    # @return [Project]
+    # @raise [NotFound]
+    def self.locate(dir = Dir.pwd)
+      project = find(dir) || new(File.expand_path(dir))
+      return project if project.layout
+
+      raise NotFound, "#{project.root} doesn't look like a DragonRuby project " \
+        "(no #{PIN_FILE}, mygame/app/main.rb or app/main.rb)."
+    end
+
+    # @return [String]
+    attr_reader :root
+
+    # @param root [String]
+    def initialize(root)
+      @root = root
+    end
+
+    # @return [Symbol, nil] +:full+, +:game_only+, or nil if neither fits
+    def layout
+      if File.file?(File.join(root, "mygame", "app", "main.rb"))
+        :full
+      elsif File.file?(File.join(root, "app", "main.rb"))
+        :game_only
+      end
+    end
+
+    # @return [String] the directory passed to +dragonruby+
+    def game_dir
+      (layout == :game_only) ? root : File.join(root, "mygame")
+    end
+
+    # @return [String]
+    def pin_path
+      File.join(root, PIN_FILE)
+    end
+
+    # @return [Engine::Spec, nil] the pinned engine, without a platform
+    # @raise [Error] if the pin file can't be parsed
+    def pin
+      return nil unless File.file?(pin_path)
+
+      line = File.readlines(pin_path, chomp: true).map(&:strip).find { |l| !l.empty? && !l.start_with?("#") }
+      raise Error, "#{PIN_FILE} is empty." unless line
+
+      Engine::Spec.parse(line)
+    end
+
+    # Pins +installation+'s version and tier. The platform is left out so the
+    # pin works on every developer's machine.
+    #
+    # @param installation [Engine::Installation]
+    # @return [void]
+    def pin!(installation)
+      File.write(pin_path, "#{installation.version}-#{installation.tier}\n")
+    end
+
+    # @param relative [String]
+    # @return [String]
+    def path(*relative)
+      File.join(root, *relative)
+    end
+  end
+end

data/lib/dr_talon/runner.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module DrTalon
+  # Builds and runs the commands of a project's installed engine:
+  # +dragonruby+, +dragonruby-publish+ and +dragonruby-httpd+.
+  class Runner
+    # The project doesn't have the needed engine binary installed.
+    class MissingBinary < Error; end
+
+    # DragonRuby writes these while running and building.
+    GENERATED_DIRS = %w[builds logs tmp errors].freeze
+
+    TEST_PATTERN = "*_tests.rb"
+    TEST_DIRS = %w[test tests].freeze
+
+    # Environment for running without a window, e.g. in CI.
+    HEADLESS_ENV = {"SDL_VIDEO_DRIVER" => "dummy", "SDL_AUDIO_DRIVER" => "dummy"}.freeze
+
+    # Replaces the current process. Separate so tests can stub it.
+    #
+    # @param argv [Array<String>]
+    # @param chdir [String]
+    def self.exec_process(argv, chdir:)
+      Process.exec(*argv, chdir: chdir)
+    end
+
+    # @param project [Project]
+    def initialize(project)
+      @project = project
+    end
+
+    # @param name [String]
+    # @return [String] absolute path to the binary in the project root
+    # @raise [MissingBinary]
+    def binary(name = "dragonruby")
+      path = [name, "#{name}.exe"].map { |candidate| @project.path(candidate) }.find { |p| File.file?(p) }
+      return path if path
+
+      hint =
+        if name != "dragonruby" && @project.layout == :game_only
+          "Game-only projects only get the dragonruby binary; build and serve need DragonRuby's full layout."
+        else
+          "Install the engine with `talon engine use`."
+        end
+      raise MissingBinary, "No #{name} in #{@project.root}. #{hint}"
+    end
+
+    # @return [String] the game directory as +dragonruby+ expects it
+    def game_arg
+      (@project.layout == :game_only) ? "." : "mygame"
+    end
+
+    # @param args [Array<String>] passed through, e.g. --record
+    # @return [Array<String>]
+    def run_command(args = [])
+      [binary, game_arg, *args]
+    end
+
+    # Packages every platform into builds/ without uploading.
+    #
+    # @param args [Array<String>] passed through to dragonruby-publish
+    # @return [Array<String>]
+    def build_command(args = [])
+      [binary("dragonruby-publish"), "--only-package", *args, game_arg]
+    end
+
+    # @param dir [String] directory to serve
+    # @param port [Integer]
+    # @return [Array<String>]
+    def serve_command(dir, port)
+      [binary("dragonruby-httpd"), dir, port.to_s]
+    end
+
+    # @param file [String] relative to the game directory
+    # @return [Array<String>]
+    def test_command(file)
+      [binary, game_arg, "--test", file]
+    end
+
+    # @return [String, nil] the newest HTML5 build, relative to the project root
+    def html5_build
+      Dir.glob("builds/*-html5-*/", base: @project.root)
+        .select { |dir| File.file?(@project.path(dir, "index.html")) }
+        .max_by { |dir| File.mtime(@project.path(dir)) }
+        &.chomp("/")
+    end
+
+    # Test files to run, relative to the game directory.
+    #
+    # @param paths [Array<String>] files or directories, relative to +base+;
+    #   all of test/ and tests/ when empty
+    # @param base [String] what +paths+ are relative to (the working directory)
+    # @return [Array<String>]
+    # @raise [Error] if a path is missing or outside the game directory
+    def test_files(paths = [], base: Dir.pwd)
+      game_dir = File.expand_path(@project.game_dir)
+
+      files =
+        if paths.empty?
+          TEST_DIRS.flat_map { |dir| Dir.glob(File.join(dir, "**", TEST_PATTERN), base: game_dir) }
+        else
+          paths.flat_map { |path| expand_test_path(File.expand_path(path, base), game_dir) }
+        end
+
+      files.uniq.sort
+    end
+
+    # Runs one test file and reads the outcome from DragonRuby's output.
+    #
+    # @param file [String] relative to the game directory
+    # @param timeout [Numeric] seconds before the run is killed
+    # @param headless [Boolean] run without a window
+    # @return [TestReport]
+    def run_test(file, timeout: 120, headless: true)
+      env = headless ? HEADLESS_ENV.reject { |key, _| ENV.key?(key) } : {}
+      reader, writer = IO.pipe
+      # Its own process group, so a timeout can stop anything it started that
+      # still holds the output pipe open.
+      group = Gem.win_platform? ? {new_pgroup: true} : {pgroup: true}
+      pid = Process.spawn(env, *test_command(file), chdir: @project.root, out: writer, err: writer, in: File::NULL, **group)
+      writer.close
+      output = Thread.new { reader.read }
+
+      exited = wait(pid, timeout)
+      stop(pid) unless exited
+      report = exited ? TestReport.parse(output.value) : TestReport.timeout(output.value)
+      pid = nil
+      report
+    ensure
+      # Interrupted (e.g. Ctrl-C, which the separate process group doesn't
+      # receive) or failed: don't leave DragonRuby running.
+      stop(pid) if pid
+      writer&.close unless writer&.closed?
+      reader&.close
+    end
+
+    # Deletes what DragonRuby generates while running and building.
+    #
+    # @return [Array<String>] removed paths, relative to the project root
+    def clean
+      dirs = GENERATED_DIRS.dup
+      dirs += GENERATED_DIRS.map { |dir| "mygame/#{dir}" } if @project.layout == :full
+
+      dirs.select { |dir| File.directory?(@project.path(dir)) }.each do |dir|
+        FileUtils.rm_rf(@project.path(dir))
+      end
+    end
+
+    private
+
+    def expand_test_path(path, game_dir)
+      unless path == game_dir || path.start_with?(game_dir + File::SEPARATOR)
+        raise Error, "#{path} is outside the game directory (#{game_dir})."
+      end
+
+      relative = path.delete_prefix(game_dir).delete_prefix(File::SEPARATOR)
+      if File.directory?(path)
+        Dir.glob(File.join("**", TEST_PATTERN), base: path).map { |file| relative.empty? ? file : File.join(relative, file) }
+      elsif File.file?(path)
+        [relative]
+      else
+        raise Error, "#{path} doesn't exist."
+      end
+    end
+
+    # @return [Boolean] whether the process exited before the timeout
+    def wait(pid, timeout)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      loop do
+        return true if Process.waitpid(pid, Process::WNOHANG)
+        return false if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+
+        sleep 0.05
+      end
+    end
+
+    def stop(pid)
+      target = Gem.win_platform? ? pid : -pid
+      Process.kill(:TERM, target)
+      return if wait(pid, 5)
+
+      Process.kill(:KILL, target)
+      Process.waitpid(pid)
+    rescue Errno::ESRCH, Errno::ECHILD
+      nil
+    end
+  end
+end

data/lib/dr_talon/talon_framework.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module DrTalon
+  # Support for projects built on the Talon game framework
+  # (https://github.com/asimmons91/talon): detecting it, and keeping the
+  # requires of generated scenes, components and prefabs in app/main.rb.
+  module TalonFramework
+    REPOSITORY = "asimmons91/talon"
+    GITHUB_KEY = %r{\Agithub:#{Regexp.escape(REPOSITORY)}(/|\z)}
+    # Where Talon's entry file is vendored by default.
+    REQUIRE = "vendor/talon/talon.rb"
+
+    BEGIN_MARKER = "# >>> talon generate: keep this block; `talon generate` adds requires to it"
+    END_MARKER = "# <<< talon generate"
+    BLOCK = /^#{Regexp.escape(BEGIN_MARKER)}\n(.*?)^#{Regexp.escape(END_MARKER)}$/m
+
+    # Load order inside the block: superclasses and helpers before the
+    # scenes that use them.
+    KIND_ORDER = %w[components prefabs scenes].freeze
+
+    # Raised when generating Talon code in a project that doesn't use it.
+    class NotUsed < Error; end
+
+    module_function
+
+    # The Talon entry in dependencies.rb: from its GitHub repository, named
+    # talon, or a local path through a talon checkout.
+    #
+    # @param project [Project]
+    # @return [Deps::Dependency, nil]
+    def dependency(project)
+      Deps::Manifest.for(project).dependencies.find do |dependency|
+        dependency.key.match?(GITHUB_KEY) ||
+          dependency.name == "talon" ||
+          (dependency.is_a?(Deps::PathDependency) && dependency.path.split("/").include?("talon"))
+      end
+    rescue Deps::ManifestError
+      nil
+    end
+
+    # @param project [Project]
+    # @return [Boolean] whether dependencies.rb declares Talon
+    def used_by?(project)
+      !dependency(project).nil?
+    end
+
+    # @param project [Project]
+    # @return [String] the game-relative require for Talon's entry file,
+    #   wherever the project vendors it
+    def require_path(project)
+      found = dependency(project)
+      found ? "#{found.destination}/talon.rb" : REQUIRE
+    end
+
+    # @param project [Project]
+    # @return [void]
+    # @raise [NotUsed]
+    def require_used!(project)
+      return if used_by?(project)
+
+      raise NotUsed, "This project doesn't use Talon. Add it with `talon add github:#{REPOSITORY} --path lib`, " \
+        "or start from the Talon template with `talon new NAME --template talon`."
+    end
+
+    # Adds +line+ to the requires block in +main_rb+, keeping the block in
+    # {KIND_ORDER}.
+    #
+    # @param main_rb [String] path to app/main.rb
+    # @param line [String] e.g. require "app/scenes/title.rb"
+    # @return [Symbol] +:added+, +:present+ or +:no_block+ (the caller should
+    #   tell the user to add the line themselves)
+    def add_require(main_rb, line)
+      content = File.file?(main_rb) ? File.read(main_rb) : ""
+      match = BLOCK.match(content)
+      return :no_block unless match
+
+      lines = match[1].lines(chomp: true).reject(&:empty?)
+      return :present if lines.include?(line)
+
+      # Other lines keep their order at the top; generated ones follow,
+      # grouped by kind and sorted by name.
+      sorted = (lines + [line]).each_with_index.sort_by do |entry, index|
+        kind = entry[%r{"app/([^/]+)/}, 1]
+        kind ? [KIND_ORDER.index(kind) || KIND_ORDER.size, entry] : [-1, index]
+      end.map(&:first)
+      block = [BEGIN_MARKER, *sorted, END_MARKER].join("\n")
+      File.write(main_rb, content.sub(BLOCK) { block })
+      :added
+    end
+
+    # @param name [String] e.g. "main_menu", "MainMenu", "main-menu"
+    # @return [Array(String, String)] the class name and file name
+    # @raise [Error] for names that aren't a plain identifier
+    def names(name)
+      unless name.match?(/\A[A-Za-z][A-Za-z0-9_-]*\z/)
+        raise Error, "Invalid name \"#{name}\". Use letters, digits, - and _, starting with a letter (e.g. MainMenu)."
+      end
+
+      words = name.gsub(/([a-z\d])([A-Z])/, '\1_\2').split(/[-_]/).reject(&:empty?)
+      [words.map { |word| word[0].upcase + word[1..] }.join, words.map(&:downcase).join("_")]
+    end
+  end
+end

data/lib/dr_talon/templates/bare/main_tests.rb.tt

@@ -0,0 +1,7 @@
+# DragonRuby runs each method named test_* that takes (args, assert).
+# Run them with `talon test`; add files named *_tests.rb to this directory.
+class MainTests
+  def test_tests_get_dragonruby_args(args, assert)
+    assert.true! args.respond_to?(:outputs), "tests receive the same args as tick"
+  end
+end

data/lib/dr_talon/templates/bare/rubocop.yml.tt

@@ -0,0 +1,8 @@
+inherit_gem:
+  rubocop-rails-omakase: rubocop.yml
+
+AllCops:
+  Include:
+    - "mygame/**/*.rb"
+  Exclude:
+    - "mygame/vendor/**/*"

data/lib/dr_talon/templates/bare/solargraph.yml.tt

@@ -0,0 +1,24 @@
+---
+include:
+  - "mygame/**/*.rb"
+exclude:
+  - "mygame/tmp/**/*"
+require: []
+domains: []
+reporters:
+  - rubocop
+formatter:
+  rubocop:
+    cops: safe
+    except: []
+    only: []
+    extra_args: []
+type_checker:
+  rules: {}
+require_paths: []
+plugins:
+  - solargraph-dragonruby
+<% if talon? -%>
+  - solargraph-dr_talon
+<% end -%>
+max_files: 5000

data/lib/dr_talon/templates/lib/app/main.rb.tt

@@ -0,0 +1,13 @@
+require "lib/<%= file_name %>.rb"
+
+# A small demo of the library; the game DragonRuby runs from this directory.
+def tick(args)
+  args.outputs.labels << {
+    x: 640,
+    y: 360,
+    text: "<%= module_name %> #{<%= module_name %>::VERSION}",
+    size_px: 30,
+    anchor_x: 0.5,
+    anchor_y: 0.5
+  }
+end

data/lib/dr_talon/templates/lib/lib/library.rb.tt

@@ -0,0 +1,4 @@
+require_relative "<%= file_name %>/version"
+
+module <%= module_name %>
+end

data/lib/dr_talon/templates/lib/lib/version.rb.tt

@@ -0,0 +1,3 @@
+module <%= module_name %>
+  VERSION = "0.1.0"
+end

data/lib/dr_talon/templates/lib/rubocop.yml.tt

@@ -0,0 +1,9 @@
+inherit_gem:
+  rubocop-rails-omakase: rubocop.yml
+
+AllCops:
+  Include:
+    - "**/*.rb"
+  Exclude:
+    - "vendor/**/*"
+    - "tmp/**/*"

data/lib/dr_talon/templates/lib/solargraph.yml.tt

@@ -0,0 +1,23 @@
+---
+include:
+  - "app/**/*.rb"
+  - "lib/**/*.rb"
+exclude:
+  - "test/**/*"
+  - "vendor/**/*"
+require: []
+domains: []
+reporters:
+  - rubocop
+formatter:
+  rubocop:
+    cops: safe
+    except: []
+    only: []
+    extra_args: []
+type_checker:
+  rules: {}
+require_paths: []
+plugins:
+  - solargraph-dragonruby
+max_files: 5000

data/lib/dr_talon/templates/lib/test/test_helper.rb.tt

@@ -0,0 +1 @@
+require "lib/<%= file_name %>.rb"

data/lib/dr_talon/templates/lib/test/tests.rb.tt

@@ -0,0 +1,8 @@
+require "test/test_helper.rb"
+
+# Run with: talon test
+class <%= module_name %>Tests
+  def test_has_a_version(args, assert)
+    assert.true! <%= module_name %>::VERSION.is_a?(String), "VERSION should be a String"
+  end
+end

data/lib/dr_talon/templates/shared/Gemfile.tt

@@ -0,0 +1,10 @@
+source "https://rubygems.org"
+
+# Editor and lint tooling only. DragonRuby doesn't load gems; game
+# dependencies go in <%= dependencies_hint %>.
+gem "rubocop-rails-omakase", require: false
+gem "solargraph", require: false
+gem "solargraph-dragonruby", require: false
+<% if talon? -%>
+gem "solargraph-dr_talon", require: false
+<% end -%>

data/lib/dr_talon/templates/shared/README.md.tt

@@ -0,0 +1,45 @@
+# <%= title %>
+
+<% if talon? -%>
+A [DragonRuby](https://dragonruby.org) game built on [Talon](https://github.com/<%= talon_repository %>).
+<% elsif layout == :full -%>
+A [DragonRuby](https://dragonruby.org) game.
+<% else -%>
+A [DragonRuby](https://dragonruby.org) library.
+<% end -%>
+
+## Setup
+
+<% if commit_engine? -%>
+The DragonRuby engine (<%= engine.version %> <%= engine.tier %>) is committed with the project.
+<% else -%>
+The project pins DragonRuby <%= engine.version %> (<%= engine.tier %>) in `.dragonruby-version`; the engine itself isn't committed. Install it with [talon](https://github.com/asimmons91/dr_talon):
+
+```bash
+talon engine import path/to/dragonruby-<%= engine.tier %>-<%= engine.platform %>.zip   # once per machine
+talon engine use
+```
+<% end -%>
+
+Editor tooling (RuboCop, Solargraph):
+
+```bash
+bundle install
+```
+
+## Running
+
+```bash
+<% if layout == :full -%>
+talon run      # ./dragonruby mygame
+talon test     # *_tests.rb in mygame/tests/
+talon build    # package every platform into builds/
+talon serve    # play the HTML5 build at http://localhost:8080/
+<% if talon? -%>
+talon generate scene|component|prefab NAME
+<% end -%>
+<% else -%>
+talon run      # ./dragonruby .
+talon test     # ./dragonruby . --test for each test/*_tests.rb
+<% end -%>
+```

data/lib/dr_talon/templates/shared/editorconfig.tt

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+end_of_line = lf
+charset = utf-8
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true

data/lib/dr_talon/templates/shared/gitignore.tt

@@ -0,0 +1,19 @@
+# DragonRuby
+/builds/
+/logs/
+/tmp/
+/errors/
+<% if layout == :full -%>
+/mygame/errors/
+<% end -%>
+
+# Ruby tooling
+/.bundle/
+
+# Editors
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets

data/lib/dr_talon/templates/talon/game/dependencies.rb.tt

@@ -0,0 +1,3 @@
+# DragonRuby dependencies, vendored into vendor/ by `talon install`.
+# Add more with `talon add github:owner/repo`.
+github "<%= talon_repository %>", path: "lib"

data/lib/dr_talon/templates/talon/game/main.rb.tt

@@ -0,0 +1,9 @@
+require "<%= talon_require %>"
+
+<%= requires_block %>
+
+def tick(args)
+  $game ||= Talon::Game.new(Title.new)
+  $game.args = args
+  $game.tick
+end

data/lib/dr_talon/templates/talon/game/spin.rb.tt

@@ -0,0 +1,7 @@
+# Turns its game object and draws it as a sprite.
+class Spin < Talon::Component
+  prop :speed, default: 1
+
+  on_update { go.angle = (go.angle || 0) + speed }
+  on_draw { outputs.sprites << go }
+end

data/lib/dr_talon/templates/talon/game/title.rb.tt

@@ -0,0 +1,8 @@
+# The first scene. Add more with `talon generate scene NAME` and switch with
+#   game.change_scene(OtherScene.new)
+class Title < Talon::Scene
+  on_enter do
+    spawn(:logo, x: 640, y: 360, w: 128, h: 128, anchor_x: 0.5, anchor_y: 0.5,
+          path: "sprites/square/blue.png") { |go| go.add(Spin) }
+  end
+end

data/lib/dr_talon/templates/talon/game/title_tests.rb.tt

@@ -0,0 +1,16 @@
+require "<%= talon_require %>"
+require "app/components/spin.rb"
+require "app/scenes/title.rb"
+
+class TitleTests
+  def test_title_spins_the_logo(args, assert)
+    scene = Title.new
+    game = Talon::Game.new(scene)
+    game.args = args
+    3.times { game.tick }
+
+    logo = scene.find { |go| go.name == :logo }
+    assert.true! logo, "the title scene should spawn a logo"
+    assert.equal! logo.angle, 3
+  end
+end

data/lib/dr_talon/templates/talon/generate/component.rb.tt

@@ -0,0 +1,19 @@
+# A component: behaviour attached to a game object with go.add(<%= class_name %>).
+class <%= class_name %> < Talon::Component
+  # Props are plain attributes set from go.add(<%= class_name %>, name: value).
+  # prop :speed, default: 1
+
+  # State lives in args.state, so it survives hot reloads.
+  # state :count, default: 0
+
+  on_start do
+  end
+
+  on_update do
+    # Runs every tick. go is the game object; args, inputs and outputs are available.
+  end
+
+  on_draw do
+    # Runs every tick after all updates, e.g. outputs.sprites << go
+  end
+end