squib 0.11.0 → 0.12.0

data/docs/guides/getting-started/part_3_workflows.rst

@@ -1,4 +1,46 @@
 The Squib Way pt 3: Workflows
 ===============================
 
-To be written.
+.. warning::
+
+  Under construction
+
+As we mentioned at the end :doc:`/guides/getting-started/part_2_iconography`, we've pretty much got most of what we need to prototype a game through completion. From here on out, the :doc:`/dsl/index` will be your best resource for getting things done. Everything from here one out is optional, but useful.
+
+But, as you explore Squib's features and work away at your games, you'll pick up a few tricks and conventions to follow that makes your time easier. After years of developing games with Squib, here are some helpful ways of improving your workflow.
+
+Improving your workflow comes down to a few principles:
+
+  * **Automate what will be tedious**. There's a balance here. What do you anticipate will change about your game as you develop it? What do you anticipate will *not* change? If you automate *everything*, you will probably spend more time on automating than game development. If you don't automate anything, you'll be re-making every component whenever you make a game design change.
+  * **Focus on one thing only: visual, game, or build**. Cognitively, you'll have an easier time when you focus on one thing and one thing only. The more loose ends you need to keep in your head, the more mistakes you'll make.
+
+Additionally, improving your workflow can help you pivot to other tasks you might need for polishing your game later on, such as:
+
+  * Quickly building one card at a time to reduce the time between builds
+  * Maintaining a printer-friendly, black-and-white version of your game in tandem with a color version
+  * Building annotated figures for your rulebook
+  * Rolling back to older versions of your game
+
+Organizing Your Project
+-----------------------
+
+Most games involve build multiple decks. Initially, you might think to put all of your Ruby code inside one file. That can work, but it gets slow and cumbersome. Instead, I like to organize my code into separate source code files inside of a `src` directory.
+
+Keeping your artwork in its own folder will also make it easier for you to find what you need later on. Also, using `img_dir` parameter in the `config.yml` will let you switch the entire image directory over in one
+
+Using a Rakefile
+----------------
+
+
+
+* Setting up rake tasks
+* Advanced project layout: splitting out decks into different files
+* Testing individual files (build groups, ranges, id-lookup)
+* Marketing images (using output as images, dependency in Rakefile)
+* Rulebook figures (build groups, annotate after saving)
+* Switch from built-in layouts to your own layout
+* Launch what you need with Launchy
+* Auto-building with Guard
+* Maintaining color and black-and-white builds (build groups, multiple layout files). Changing build sessions within Guard
+* Configuring different things for each build
+* Git (save to json, tagging, rolling back, Gemfile.lock)

data/docs/guides/getting-started/part_4_ruby_power.rst

@@ -0,0 +1,18 @@
+The Squib Way pt 4: Ruby Power!
+===============================
+
+.. warning::
+
+  To be written.
+
+
+This part is about cataloging some powerful things you can do if you're willing to write some Ruby.
+
+* Modifying XML at runtime (e.g. convert to black-and-white from color)
+* Using Travis to build and then post to something like Dropbox
+* Scaling the size of text based on its contents
+* Advanced Array techniques: inject, transpose, map, join (use the pre-req example)
+* Building newlines yourself (i.e. with your own placeholder like "%n" in Your Last Heist)
+* Summarization card backs for Your Last Heist as an example
+* "Lacks" string for Your Last Heist
+* Rules doc written in Markdown

data/docs/guides/git.rst

@@ -1,12 +1,13 @@
 Squib + Git
 ===========
 
-.. note::
+.. warning::
 
   To be written
 
 
 Ideas:
+  * .gitignore
   * Workflow
   * Tracking binary data (show json method)
   * Snippet about "what's changed"

data/docs/guides/guard.rst

@@ -0,0 +1,84 @@
+Autobuild with Guard
+====================
+
+.. warning::
+
+  Under construction - going to fold this into the Workflow guide. For now, you can see my samples. This is mostly just a brain dump.
+
+Throughout your prototyping process, you'll be making small adjustments and then examining the graphical output. Re-running your code can get tedious, because you're cognitively switching from one context to another, e.g. editing x-y coordinates to running your code.
+
+Ruby has a great tool for this: `Guard <https://github.com/guard/guard>`_. With Guard, you specify one configuration file (i.e. a ``Guardfile``), and then Guard will *watch* a set of files, then execute a *task*. There are many ways of executing a task, but the cleanest way is via a ``rake`` in a ``Rakefile``.
+
+Project layout
+--------------
+
+Here's our project layout:
+
+.. code-block:: text
+
+  .
+  ├── config.yml
+  ├── Gemfile
+  ├── Guardfile
+  ├── img
+  │   └── robot-golem.svg
+  ├── layouts
+  │   ├── characters.yml
+  │   └── skills.yml
+  ├── Rakefile
+  └── src
+    ├── characters.rb
+    └── skills.rb
+
+Using Guard + Rake
+------------------
+
+Guard is a gem, just like Squib. When using Guard, I recommend also using Bundler. So your Gemfile will look like this.
+
+.. literalinclude:: ../../samples/project/Gemfile
+  :language: ruby
+  :linenos:
+
+And then your Rakefile might look something like this
+
+.. literalinclude:: ../../samples/project/Rakefile
+  :language: ruby
+  :linenos:
+
+To get our images directory set, and to turn on proress bars (which I recommend when working under Guard), you'll need a ``config.yml`` file that looks like this.
+
+.. literalinclude:: ../../samples/project/config.yml
+  :language: yaml
+  :linenos:
+
+Note that we are using ``load`` instead of ``require`` to run our code. In Ruby, ``require`` will only run our code once, because it's about loading a library. The ``load`` will run Ruby code no matter whether or not it's been loaded before. This doesn't usually matter, unless you're running under Guard.
+
+And then our Guardfile
+
+.. literalinclude:: ../../samples/project/Guardfile
+  :language: ruby
+  :linenos:
+
+
+So, let's say we're working on our Character deck. To run all this we can kick off our Guard with:
+
+.. code-block:: text
+
+  $ bundle exec guard -g characters
+  14:45:20 - INFO - Run 'gem install win32console' to use color on Windows
+  14:45:21 - INFO - Starting guard-rake characters
+  14:45:21 - INFO - running characters
+  Loading SVG(s) <===========================================> 100% Time: 00:00:00
+  Saving PNGs to _output/character__* <======================> 100% Time: 00:00:00
+  ]2;[running rake task: characters] watched files: []
+  [1] Characters guard(main)> ow watching at 'C:/Users/andy/code/squib/samples/project'
+
+Guard will do an initial build, then wait for file changes to be made. From here, once we edit and save anything related to characters - any Excel file, our ``characters.rb`` file, any YML file, etc, we'll rebuild our images.
+
+Guard can do much, much more. It opens up a debugging console based on `pry <http://pryrepl.org/>`_, which means if your code is broken you can test things out right there.
+
+Guard also supports all kinds of notifications too. By default it tends to beep, but you can also have visual bells and other notifications.
+
+To quit guard, type ``quit`` on their console. Or, you can do ``Ctrl+C`` to quit.
+
+Enjoy!

data/docs/guides/hello_world.rst

@@ -1,6 +1,65 @@
-Hello, World!
-=============
+Hello, World! Dissected
+=======================
 
-.. note::
+After seeing Squib's `landing page <http://squib.rocks>`_, your might find it helpful to dissect what's really going on in each line of code of a basic Squib snippet.
 
-  Under construction
+.. code-block:: ruby
+   :linenos:
+
+   require 'squib'
+
+   Squib::Deck.new width: 825, height: 1125, cards: 2 do
+     background color: 'pink'
+     rect
+     text str: ['Hello', 'World!']
+     save_png prefix: 'hello_'
+   end
+
+Let’s dissect this:
+
+* Line 1: this code will bring in the Squib library for us to use. Keep this at the top.
+* Line 2: By convention, we put a blank line between our require statements and the rest of our code
+* Line 3: Define a new deck of cards. Just 2 cards. 825 pixels wide etc. Squib also supports :doc:`/units` if you prefer to specify something like ``'2.75in'``.
+* Line 4: Set the background to pink. Colors can be in various notations, and supports linear and radial graidents - see :doc:`/colors`.
+* Line 5: Draw a rectangle around the edge of each card. Note that this has no arguments, because :doc:`/parameters`. The defaults can be found in the DSL reference for the :doc:`/dsl/rect` method.
+* Line 6: Put some text in upper-left the corner of the card, using the default font, etc. See the :doc:`/dsl/text` DSL method for more options. The first card will have ``'Hello'`` and the second card will have ``'World'`` because :doc:`/arrays`.
+* Line 7: Save our card out to a png files called ``hello_00.png`` and ``hello_01.png`` saved in the ``_output`` folder.
+
+Dissection of "Even Bigger..."
+------------------------------
+
+On Squib's `landing page <http://squib.rocks>`_ we end with a pretty complex example. It's compact and designed to show how much you can get done with a little bit of code. Here's a dissection of that.
+
+.. code-block:: ruby
+   :linenos:
+
+   require 'squib'
+
+   Squib::Deck.new(cards: 4, layout: %w(hand.yml even-bigger.yml)) do
+     background color: '#230602'
+     deck = xlsx file: 'even-bigger.xlsx'
+     svg file: deck['Art'], layout: 'Art'
+
+     %w(Title Description Snark).each do |key|
+       text str: deck[key], layout: key
+     end
+
+     %w(Attack Defend Health).each do |key|
+       svg file: "#{key.downcase}.svg", layout: "#{key}Icon"
+       text str: deck[key], layout: key
+     end
+
+     save_png prefix: 'even_bigger_'
+     showcase file: 'showcase.png', fill_color: '#0000'
+     hand file: 'hand.png', trim: 37.5, trim_radius: 25, fill_color: '#0000'
+   end
+
+* Line 3: Make 4 cards. Use two layouts: the built-in hand.yml (see :doc:`/layouts`) and then our own layout. The layouts get merged, with our own `even-bigger.yml` overriding ``hand.yml`` whenever they collide.
+* Line 5: Read some data from an Excel file, which amounts to a column-based hash of arrays, so that each element of an array corresponds to a specific data point to a given card. For example, ``3`` in the ``'Attack'`` column will be put on the second card.
+* Line 6: Using the Excel data cell for the filename, we can customize a different icon for every card. But, every SVG in this command will be styled according to the ``Art`` entry in our layout (i.e. in ``even-bigger.yml``)
+* Line 8: Iterate over an array of strings, namely, ``'Title'``, ``'Description'``, and ``'Snark'``.
+* Line 9: Draw text for the (Title, Description, or Snark), using *their* styling rules in our layout.
+* Line 13: Using `Ruby String interpolation <https://en.wikibooks.org/wiki/Ruby_Programming/Syntax/Literals#Interpolation>`_, lookup the appropriate icon (e.g. ``'attack.svg'``), converted to lowercase letters, and then using the Icon layout of that for styling (e.g. ``'AttackIcon'`` or ``'DefendIcon'``)
+* Line 17: Render every card to individual PNG files
+* Line 18: Render a "showcase" of cards, using a perspective-reflect effect. See :doc:`/dsl/showcase` method.
+* Line 19: Render a "hand" of cards (spread over a circle). See :doc:`/dsl/hand` method.

data/docs/guides/projects.rst

@@ -0,0 +1,35 @@
+Squib in Action
+===============
+
+Squib is in use by a lot of people! You can learn a lot from looking at how a whole project is put together.
+
+A good way to peruse Squib code is to search for Ruby files on GitHub that have the phrase ``require 'squib'`` in them. And these are the just the people who have decided to release their code open source!
+
+My Projects
+-----------
+
+Here are some of my own board and card games that use Squib. They are all under "active" development, which means that sometimes I leave them alone for long periods of time ;)
+
+  * `Your Last Heist <http://github.com/andymeneely/project-timber-wolf>`_ is a big-box cooperative game. Lots of really cool Squib things in here, including lots of Rake features, color+bw, and showing how skills can "level up" on their backs by diff'ing the stats in Squib. You can see what the components look like at `the game website <http://yourlastheist.com>`_. Also: the best game I've ever made.
+  * `Victory Point Salad <https://github.com/andymeneely/victory-point-salad>`_. A card-only game with lots and lots and lots of cards. Pretty straightforward as far as Squib usage goes, but it's a good peek into how I like to use Squib. Also: the funniest game I've made.
+  * `Junk Land <https://github.com/andymeneely/junk-land>`_ A game I made prior to making starting Squib, but then ported over to Squib while developing Squib. Uses some strange features of SVG, but also a good intro. Also: the scrappiest game I've made.
+
+.. note::
+
+  Want to donate back to Squib? Volunteer to playtest these games :)
+
+Other Projects using Squib
+--------------------------
+
+Poking around GitHub, here are a few sightings of Squib:
+
+  * `Ecovalia <https://github.com/evolve2k/ecovalia-game>`_ - a game rapidly prototyped in a hackathon. Squib is featured in their video!
+  * `Werewolf <https://github.com/Xpktro/werewolf>`_ implemented and even uses GitHub releases!
+  * `Cult Following <https://github.com/ericathegreat/Cult-Following>`_ is a neat-looking project
+  * ScrapyardArmory's `Dysplacement <https://www.thegamecrafter.com/games/dysplacement>`_ was used with Squib, and **won** the `Worker Placement contest <https://www.thegamecrafter.com/games/dysplacement>`_ over at TheGameCrafter.
+  * `Mad World <https://github.com/spilth/madworld>`_ uses CircleCI to build, even with some custom fonts.
+
+Want yours here?
+----------------
+
+Create an issue on Github and ask for a link her and  we'll add it here!

data/docs/install.rst

@@ -13,7 +13,9 @@ Squib works with both x86 and x86_64 versions of Ruby.
 Typical Install
 ---------------
 
-Regardless of your OS, installation is::
+Regardless of your OS, installation is
+
+.. code-block:: none
 
   $ gem install squib
 

data/docs/layouts.rst

@@ -250,7 +250,7 @@ economy.yml
 https://github.com/andymeneely/squib/tree/master/lib/squib/layouts/economy.yml
 
 tuck_box.yml
-~~~~~~~~~~~
+~~~~~~~~~~~~
 
 Based on TheGameCrafter's template.
 
@@ -263,7 +263,7 @@ https://github.com/andymeneely/squib/tree/master/lib/squib/layouts/tuck_box.yml
 
 
 hand.yml
-~~~~~~~~~~~
+~~~~~~~~
 
 .. raw:: html
 
@@ -273,7 +273,7 @@ hand.yml
 https://github.com/andymeneely/squib/tree/master/lib/squib/layouts/hand.yml
 
 playing_card.yml
-~~~~~~~~~~~
+~~~~~~~~~~~~~~~~
 
 .. raw:: html
 

data/docs/learning.rst

@@ -6,5 +6,7 @@ Learning Squib
 
    guides/hello_world
    guides/getting-started/index
-   guides/git
+   guides/projects
    guides/game_icons
+   guides/git
+   guides/guard

data/docs/parameters.rst

@@ -1,13 +1,17 @@
 Parameters are Optional
 =======================
 
-Squib is all about sane defaults and shorthand specification. Arguments to DSL methods are almost always using hashes, which look a lot like [Ruby 2.0's named parameters](http://www.ruby-doc.org/core-2.0.0/doc/syntax/calling_methods_rdoc.html#label-Keyword+Arguments). This means you can specify your parameters in any order you please. All parameters are optional.
+Squib is all about sane defaults and shorthand specification. Arguments to DSL methods are almost always using hashes, which look a lot like `Ruby 2.0's named parameters <http://www.ruby-doc.org/core-2.0.0/doc/syntax/calling_methods_rdoc.html#label-Keyword+Arguments>`_. This means you can specify your parameters in any order you please. All parameters are optional.
 
-For example `x` and `y` default to 0 (i.e. the upper-left corner of the card). Any parameter that is specified in the command overrides any Squib defaults, `config.yml` settings, or layout rules.
+For example ``x`` and ``y`` default to ``0`` (i.e. the upper-left corner of the card). Any parameter that is specified in the command overrides any Squib defaults or layout rules.
 
-.. highlight:: none
+You must use *named parameters* rather than *positional parameters*. For example::
 
-Note: you MUST use named parameters rather than positional parameters. For example: ``save :png`` will lead to an error like this::
+  save(:png) # wrong
+
+will lead to an error like this:
+
+.. code-block:: none
 
     C:/Ruby200/lib/ruby/gems/2.0.0/gems/squib-0.0.3/lib/squib/api/save.rb:12:in `save': wrong number of arguments (2 for 0..1) (ArgumentError)
         from deck.rb:22:in `block in <main>'
@@ -16,11 +20,15 @@ Note: you MUST use named parameters rather than positional parameters. For examp
         from deck.rb:18:in `new'
         from deck.rb:18:in `<main>'
 
-Instead, you must name the parameters: `save format: :png`
+Instead, you must name the parameters::
+
+   save(format: :png) # the right way
 
 .. warning::
 
   If you provide an option to a DSL method that the DSL method does not recognize, Squib ignores the extraenous option without warning. For example, these two calls have identical behavior::
 
     save_png prefix: 'front_'
-    save_png prefix: 'front_', narf: true
+    save_png prefix: 'front_', narf: true # narf has no effect
+
+  This can be troublesome when you accidentally misspell an option and don't realize it.

data/docs/text_feature.rst

@@ -1,7 +1,6 @@
 The Mighty text Method
 ======================
 
-
 The :doc:`/dsl/text` method is a particularly powerful method with a ton of options. Be sure to check the option-by-option details in the DSL reference, but here are the highlights.
 
 Fonts
@@ -42,7 +41,7 @@ Hints
 Laying out text by typing in numbers can be confusing. What Squib calls "hints" is merely a rectangle around the text box. Hints can be turned on globally in the config file, using the :doc:`/dsl/hint` method, or in an individual text method. These are there merely for prototyping and are not intended for production. Additionally, these are not to be conflated with "rendering hints" that Pango and Cairo mention in their documentation.
 
 Extents
-------
+-------
 
 Sometimes you want size things based on the size of your rendered text. For example, drawing a rectangle around card's title such that the rectangle perfectly fits. Squib returns the final rendered size of the text so you can work with it afterward. It's an array of hashes that correspond to each card. The output looks like this::
 
@@ -56,7 +55,7 @@ will output::
   [{:width=>109, :height=>55}, {:width=>142, :height=>55}] # Hello was 109 pixels wide, World 142 pixels
 
 Embedding Images
-------------------
+----------------
 
 Squib can embed icons into the flow of text. To do this, you need to define text keys for Squib to look for, and then the corresponding files. The object given to the block is a ``TextEmbed``, which supports PNG and SVG. Here's a minimal example::
 
@@ -69,18 +68,48 @@ Markup
 
 See :ref:`Markup <text-markup>` in  :doc:`/dsl/text`.
 
-Examples
---------
+Samples
+-------
+
+These samples are maintained in the `repository here <https://github.com/andymeneely/squib/tree/master/samples>`_ in case you need some of the assets referenced.
 
-  * Examples of all of the above are crammed into the ``text_options.rb`` sample `found here <https://github.com/andymeneely/squib/tree/master/samples/text_options.rb>`_
-  * The ``embed_text.rb`` sample has more examples of embedding text, which can be `found here <https://github.com/andymeneely/squib/tree/master/samples/embed_text.rb>`_
-  * The ``config_text_markup.rb`` sample demonstrates how quoting can be configured, `found here <https://github.com/andymeneely/squib/tree/master/samples/config_text_markup.rb>`_
+Sample: _text.rb
+^^^^^^^^^^^^^^^^
 
-And this one too:
+.. literalinclude:: ../samples/text/_text.rb
+  :language: ruby
+  :linenos:
 
 .. raw:: html
 
-  <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
-  <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/gist-embed/2.4/gist-embed.min.js"></script>
-  <code data-gist-id="52d7b8e332194946bc69" data-gist-file="_text.rb"></code>
-  <code data-gist-id="52d7b8e332194946bc69" data-gist-file="_text_00_expected.png"></code>
+  <img src="text/_text_00_expected.png" width=600 class="figure">
+
+Sample: text_options.rb
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. literalinclude:: ../samples/text_options.rb
+  :language: ruby
+  :linenos:
+
+Sample: embed_text.rb
+^^^^^^^^^^^^^^^^^^^^^
+
+.. literalinclude:: ../samples/embed_text.rb
+  :language: ruby
+  :linenos:
+
+
+Sample: config_text_markup.rb
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. literalinclude:: ../samples/config_text_markup.rb
+  :language: ruby
+  :linenos:
+
+.. literalinclude:: ../samples/config_text_markup.yml
+  :language: ruby
+  :linenos:
+
+.. literalinclude:: ../samples/config_disable_quotes.yml
+  :language: ruby
+  :linenos:

data/docs/units.rst

@@ -3,4 +3,12 @@ Unit Conversion
 
 By default, Squib thinks in pixels. This decision was made so that we can have pixel-perfect layouts without automatically scaling everything, even though working in units is sometimes easier. We provide some conversion methods, including looking for strings that end in "in", "cm", or "mm" and computing based on the current DPI. The dpi is set on `Squib::Deck.new` (not `config.yml`).
 
-Example is in `samples/units.rb` found [here](https://github.com/andymeneely/squib/tree/master/samples/units.rb)
+Here are some examples, which `lives here <https://github.com/andymeneely/squib/tree/master/samples/units.rb>`_
+
+.. literalinclude:: ../samples/units/_units.rb
+  :language: ruby
+  :linenos:
+
+.. raw:: html
+
+  <img src="units/units_00_expected.png" class="figure">