rename module, more docs

src/Swarm/Game/Entity.hs

@@ -112,7 +112,7 @@ import Data.Yaml
 import GHC.Generics (Generic)
 import Swarm.Game.Display
 import Swarm.Game.Entity.Cosmetic (WorldAttr (..))
-import Swarm.Game.Entity.Cosmetic.Specimen (worldAttributes)
+import Swarm.Game.Entity.Cosmetic.Assignment (worldAttributes)
 import Swarm.Game.Failure
 import Swarm.Game.Location
 import Swarm.Game.ResourceLoading (getDataFileNameSafe)

src/Swarm/Game/Entity/Cosmetic.hs

@@ -17,6 +17,7 @@ data NamedColor
   | Yellow
   deriving (Show)
 
+-- | 8-bit color
 type RGBColor = RGB Word8
 
 -- | High-fidelity color representation for rendering
@@ -27,11 +28,19 @@ data TrueColor
   deriving (Show)
 
 -- |
--- Ignores vty "styles", such as bold/italic/underline.
+-- A value of type @ColorLayers a@ represents the assignment of
+-- foreground and\/or background color to an 'Entity' or terrain,
+-- where @a@ may be a medium-independent (i.e. "authoritative") color
+-- representation, or medium-specific (e.g. a @vty@ color).
+-- The 'Functor' instance facilitates easy conversion from the
+-- authoritative color to the specialized representation.
+--
+-- Ignores @vty@ "styles", such as bold\/italic\/underline.
 --
 -- This is intended to facilitate multiple rendering mediums:
 --
--- * Single pixel per world cell (one color must be chosen between foreground and background, if both are specified)
+-- * Single pixel per world cell (one color must be chosen
+--   between foreground and background, if both are specified)
 -- * Pixel block per world cell (can show two colors in some stylized manner)
 -- * Glyph per world cell (can render a colored display character on a colored background)
 data ColorLayers a

src/Swarm/Game/Entity/Cosmetic/Specimen.hs → src/Swarm/Game/Entity/Cosmetic/Assignment.hs

@@ -2,7 +2,12 @@
 -- SPDX-License-Identifier: BSD-3-Clause
 --
 -- Entity and terrain coloring.
-module Swarm.Game.Entity.Cosmetic.Specimen where
+--
+-- This module is the sole "ground truth" for color
+-- assignment of entities and terrain.
+-- More specifically, it sets colors for "attributes",
+-- and the attributes are referenced by entities\/terrain.
+module Swarm.Game.Entity.Cosmetic.Assignment where
 
 import Data.Bifunctor (bimap)
 import Data.Colour.SRGB (RGB (..))

src/Swarm/Game/Scenario.hs

@@ -64,13 +64,13 @@ import Data.List.NonEmpty qualified as NE
 import Data.Map qualified as M
 import Data.Maybe (catMaybes, isNothing, listToMaybe, mapMaybe)
 import Data.Sequence (Seq)
-import Data.Set qualified as Set
 import Data.Set (Set)
+import Data.Set qualified as Set
 import Data.Text (Text)
 import Data.Text qualified as T
 import Swarm.Game.Entity
 import Swarm.Game.Entity.Cosmetic
-import Swarm.Game.Entity.Cosmetic.Specimen (worldAttributes)
+import Swarm.Game.Entity.Cosmetic.Assignment (worldAttributes)
 import Swarm.Game.Failure
 import Swarm.Game.Location
 import Swarm.Game.Recipe

src/Swarm/Game/World/Render.hs

@@ -20,7 +20,7 @@ import Linear (V2 (..))
 import Swarm.Doc.Gen (loadStandaloneScenario)
 import Swarm.Game.Display (Attribute (AWorld), defaultChar, displayAttr)
 import Swarm.Game.Entity.Cosmetic
-import Swarm.Game.Entity.Cosmetic.Specimen (terrainAttributes)
+import Swarm.Game.Entity.Cosmetic.Assignment (terrainAttributes)
 import Swarm.Game.Location
 import Swarm.Game.ResourceLoading (initNameGenerator, readAppData)
 import Swarm.Game.Scenario (Scenario, area, scenarioCosmetics, scenarioWorlds, ul, worldName)

src/Swarm/TUI/View/Attribute/Attr.hs

@@ -60,7 +60,7 @@ import Data.Text (unpack)
 import Graphics.Vty qualified as V
 import Swarm.Game.Display (Attribute (..))
 import Swarm.Game.Entity.Cosmetic
-import Swarm.Game.Entity.Cosmetic.Specimen
+import Swarm.Game.Entity.Cosmetic.Assignment
 import Swarm.TUI.View.Attribute.Util
 
 toAttrName :: Attribute -> AttrName

src/Swarm/TUI/View/Logo.hs

@@ -10,7 +10,7 @@ import Brick
 import Brick.Widgets.Center (centerLayer)
 import Data.Text (Text)
 import Data.Text qualified as T
-import Swarm.Game.Entity.Cosmetic.Specimen
+import Swarm.Game.Entity.Cosmetic.Assignment
 import Swarm.TUI.Model.Name
 import Swarm.TUI.View.Attribute.Attr
 

swarm.cabal

@@ -118,7 +118,7 @@ library
                       Swarm.Game.Display
                       Swarm.Game.Entity
                       Swarm.Game.Entity.Cosmetic
-                      Swarm.Game.Entity.Cosmetic.Specimen
+                      Swarm.Game.Entity.Cosmetic.Assignment
                       Swarm.Game.Exception
                       Swarm.Game.Location
                       Swarm.Game.Recipe