Media Libraries and Pools

The Media Library holds the images and videos available to a creation. Every resource has a name such as victory, critical_health, or score_icon. Sugar writes a media resource with & before that name:

&victory

Show one resource

show media &victory;
show chip "Perfect score" with icon => &score_icon;

Declare a Media Pool

A Media Pool is a list of Media used for random selection. It follows the same declaration and composition rules as every other list. Its exact Sugar type is shown in this first declaration:

const outcomes: List<Media> = (
  &common,
  &unusual,
  &rare,
);

Show a random member with from:

show media from outcomes;

The pool name has no & because it names a list value, not one uploaded resource.

Give entries conditions

Any list entry may use when. A false entry is left out when the list is created:

const discoveries = (
  &old_coin,
  &silver_key when luck >= 40,
  &lost_crown when luck >= 80,
);

If several entries remain when show media from runs, each has an equal chance of being chosen.

Compose pools like lists

Use + to merge lists and - to remove entries:

const standard = (&common, &unusual);
const rare = (&rare, &legendary);
const special = standard + rare;
const safe = special - (&legendary,);

List methods work too:

let available = special.filter(|entry| mediaExists(entry));

These operators create new lists; they do not change their inputs.

Select without naming a pool

show media from (&sunrise, &rain, &snow);
show media from (
  &clear_sky when weather == "CLEAR",
  &rain when weather == "RAIN",
  &snow when weather == "SNOW",
);

With no resource or pool, show media selects from the creation’s complete local Media Library:

show media;

Exclude resources from one selection

except accepts either one Media value or a list of Media:

show media from outcomes except &rare;
show media from outcomes except (&rare, &legendary);
show media except &debug_image;

It filters only that selection. It does not mutate the list or Media Library. Use list subtraction when the filtered list itself should be reusable:

const ordinary = outcomes - (&rare, &legendary);

Make the output conditional

show media from discoveries when revealReward;
show media &warning when health <= 10;
show media from outcomes except &rare when luck < 50;

The final when controls the whole output statement; a when beside a list entry controls only that entry.

Check optional resources

if mediaExists(&special_result) {
  show media &special_result;
}