NAME

Langertha::Holmgang::Sim::Roost - The answer world roost — an invented dragon roost with perches and a larder, for the example suite demo-roost

VERSION

version 0.001

SYNOPSIS

# suite.yaml: every tool names the world, the tool's name picks what it does
tools:
  - { name: feed_dragon, simulator: roost, description: …, parameters: { … required: [ dragon, food ] } }

my $sims = Langertha::Holmgang::Simulators->new;
my ( $output, $ok ) = $sims->tool_call( $state, roost => feed_dragon => { dragon => 'ember', food => 'peppers' } );

DESCRIPTION

A world without a device (contract: Langertha::Holmgang::Role::AnswerWorld; type roost): a dragon roost, freely invented for the example suite demo-roost — dragons that sit on perches and eat from a larder. It models nothing that exists and is there to show the shape of a typed answer world. Tool names, parameters and world keys are English:

survey_roost  { }                 the dragons, the perches and the larder
feed_dragon   { dragon, food }    one basket of a food from the larder to a dragon
move_dragon   { dragon, perch }   a dragon flies to another perch

Names are matched without regard to case and surrounding white space. A call the world refuses answers Error: … and changes nothing.

feed_dragon

Takes one basket of food out of the larder and adds the food to the dragon's meals. Refused when there is no such dragon, when the larder has no such food, or when none of it is left. The world does not judge the meal: a dragon eats what it is given, whether or not it is in its eats.

move_dragon

Sets the dragon's perch. Refused when there is no such dragon or perch, or when another dragon sits on the perch (one dragon per perch). The world does not compare wingspan and span: a dragon flies to a perch too small for it all the same.

State

roost:
  type: roost
  dragons:
    ember: { wingspan: 14, perch: north-crag, eats: [ coal, peppers ], meals: [] }
  perches:
    north-crag: { span: 20 }
  larder:
    peppers: 2        # baskets

dragons by name: wingspan (a number), perch (a key of perches, or absent for a dragon on the ground), eats (the foods it likes, for the survey and for a case's rules; the tools do not read it), meals (the foods it was given, in order; absent counts as none). perches by name: span, the widest wingspan the perch holds (shown, not enforced). larder: food name to a whole number of baskets.

Only the state, deterministic, neutral.

device_type

roost.

tools

my $tools = $world->tools;   # { feed_dragon => [qw( dragon food )], … }

The tools of this world with their required parameters (for the loader).

tool

my ( $output, $ok ) = $world->tool( $roost, $name, \%args, $ctx );

A tool call on the state of the roost ($roost is changed). A name not in "tools" is an error.

SUPPORT

Issues

Please report bugs and feature requests at https://github.com/Getty/langertha-holmgang/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.