styleRoleSet.assetType
- README.md3.6 KB
- about.yaml883 B
- behavior.luau818 B
- template
- type.yaml975 B
README.md
styleRoleSet (asset type)
A set of game roles and what each one gets from the scene's look, so players, enemies and pickups read apart under one art style. A role set is a folder <name>.styleRoleSet/ holding roles.yaml, README.md and .metadata.
roles.yaml
name: Toon game
summary: Heroes bold and clean, enemies heavy and dark, pickups bright with no paper.
extends: "" # another set to start from (or `look`: the set the look suits); only the roles written here change
forLooks: [comicInkCel] # looks this set suits: picked by itself when the stack has no set
forPackages: [toonBlocks]
roles:
hero:
summary: The player's own character.
variant: player # the name a stack entry targets with `variant`; "asRendered" leaves it as rendered
line: 1.6 # line and stroke weight, 1 as the look draws it
marks: { line: 1, tone: 1, fill: 1, paper: 0.33 } # how much of each kind of mark reaches it, 0 to 1
value: 0.3 # a free value 0 to 1 blocks may use (0 changes nothing)
ink: "#141026" # line colour for blocks that take one
Every field of a role may be left out: a missing field keeps the look as drawn (variant none, line 1, every mark 1, value 0, the look's ink). Marks are kept in thirds (0, 0.33, 0.67, 1). A set names at most seven variants that stack entries target; a scene draws at most eight distinct settings in its object mask (see styleKit's Known limits).
Using one
local StyleKit = require("~styleKit.StyleKit")
StyleKit.setRoles("toonGame") -- the whole game's roles, one change, every player
StyleKit.give(boss, "boss") -- one object's role, one change
print(StyleKit.roleSet("toonGame").roles.boss.line)
With no set picked (StyleKit.setRoles("")) the stack follows its look: it takes the first set whose forLooks names the look, then the first whose forPackages names the package of most of its blocks. A role the set does not know is used as the object's variant name and changes nothing else.
Writing your own
noLook: names the set a set written with extends: look sits over while no look is on (styleRoles' sets for kinds of game name toonGame), so a game's roles carry their groups (player, enemy, pickup) from the start rather than only once a look is picked.
glazes: names a glaze per variant, { tint, amount, saturation, lightness } (the Roles glaze block's settings), which StyleRoles.use adds as a Roles glaze drawn only on that variant: the colour that tells groups sharing a material apart (for example enemy: { tint: "#b01832", amount: 0.65, lightness: 0.78 }). Like lines:, it merges through extends variant by variant.
asset.create("styleRoleSet", "myRoles") starts one from the template, or copy a set and change it. Use extends: toonGame to keep every role of a set and change only the ones you write. Use extends: look for a set made for a kind of game rather than a kind of look: it is laid over whichever set the scene's look suits (and follows a look change by itself), so write only what the genre decides, typically each role's line and ink and the lines inks, and leave tone, fill, paper and value to the look's set. styleRoles ships six of these (bright platformer, arena shooter, RPG, racing, spooky, cozy). The set registers on every machine as soon as it is saved.
Known limits
- An asset of this type registers when the engine indexes its files, a moment after they are written.
- ZeroMind's description of this can lag one release behind what is installed (#19258).
The package README's Known limits lists the rest.