From 72e10a3afd19364d5df1f9948c4ad520beabd490 Mon Sep 17 00:00:00 2001 From: Tobias Nett Date: Wed, 25 May 2022 13:24:00 +0200 Subject: [PATCH] doc: migrate wiki to docsify page (#106) Co-authored-by: Josephine Rueckert --- README.md | 45 +- docs/.nojekyll | 0 docs/Action-Nodes-Decorators.md | 74 + docs/Big-Picture.md | 110 + docs/Building-a-Behavior-Tree.md | 114 + docs/Case-Study.md | 294 + docs/Control-Flow-Nodes.md | 187 + docs/Groups.md | 95 + docs/Pre-made-Behaviors-and-Nodes.md | 120 + docs/Quick-Start.md | 76 + docs/README.md | 1 + docs/Responding-to-Outside-Changes.md | 107 + docs/Step-By-Step-Tutorial.md | 247 + docs/Tree-Nodes.md | 59 + docs/_media/banner.png | Bin 0 -> 1582165 bytes docs/_media/icon.svg | 12083 ++++++++++++++++ docs/_sidebar.md | 13 + .../behavior-tree-folder.png | Bin 0 -> 4090 bytes docs/images/Groups/groups-tree-folder.png | Bin 0 -> 4806 bytes .../images/Step-By-Step-Tutorial/first-bt.png | Bin 0 -> 15161 bytes .../first-tree-structure.png | Bin 0 -> 6544 bytes .../Step-By-Step-Tutorial/second-bt.png | Bin 0 -> 28043 bytes .../images/Step-By-Step-Tutorial/third-bt.png | Bin 0 -> 29048 bytes docs/images/big-picture/bt.png | Bin 0 -> 62284 bytes docs/index.html | 65 + 25 files changed, 13688 insertions(+), 2 deletions(-) create mode 100644 docs/.nojekyll create mode 100644 docs/Action-Nodes-Decorators.md create mode 100644 docs/Big-Picture.md create mode 100644 docs/Building-a-Behavior-Tree.md create mode 100644 docs/Case-Study.md create mode 100644 docs/Control-Flow-Nodes.md create mode 100644 docs/Groups.md create mode 100644 docs/Pre-made-Behaviors-and-Nodes.md create mode 100644 docs/Quick-Start.md create mode 120000 docs/README.md create mode 100644 docs/Responding-to-Outside-Changes.md create mode 100644 docs/Step-By-Step-Tutorial.md create mode 100644 docs/Tree-Nodes.md create mode 100644 docs/_media/banner.png create mode 100644 docs/_media/icon.svg create mode 100644 docs/_sidebar.md create mode 100644 docs/images/Building-A-Behavior-Tree/behavior-tree-folder.png create mode 100644 docs/images/Groups/groups-tree-folder.png create mode 100644 docs/images/Step-By-Step-Tutorial/first-bt.png create mode 100644 docs/images/Step-By-Step-Tutorial/first-tree-structure.png create mode 100644 docs/images/Step-By-Step-Tutorial/second-bt.png create mode 100644 docs/images/Step-By-Step-Tutorial/third-bt.png create mode 100644 docs/images/big-picture/bt.png create mode 100644 docs/index.html diff --git a/README.md b/README.md index a228e86b..eaefaa5a 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,43 @@ -# Behaviors -Store for an assortment of behaviors that can be applied to creatures +
+ +
+ +_This is a module for [Terasology]. +It provides a set of behavior traits that can be applied to creatures and NPCs._ + +

👉 Documentation 👈

+ +## Contributing + +We welcome contributions to our modules, be it bug fixes or feature contributions. +Check out the [Contributor Guide][contributor-guide] on the main project wiki to learn more. + +To check out this module (and all its dependencies) to your Terasology workspace run (in the workspace root): + +``` +groovyw module recurse Behaviors +``` + +To build a module JAR for just this module run (in the workspace root): + +``` +gradlew :module:Behaviors:jar +``` + +To run all tests and static code checks for this module run (in the workspace root): + +``` +gradlew :module:Behaviors:check +``` + +### Documentation via gh-pages + +The documentation of this module is build with [docsify]. +It is served via [gh-pages]. +To preview the site you can either use the `docsify` [CLI tool](https://github.com/docsifyjs/docsify-cli) or just run a static server on the `docs` folder. + + +[Terasology]: https://github.com/MovingBlocks/Terasology +[gh-pages]: https://pages.github.com/ +[docsify]: https://docsify.js.org/#/ +[contributor-guide]: https://github.com/MovingBlocks/Terasology/wiki/Contributor-Quick-Start diff --git a/docs/.nojekyll b/docs/.nojekyll new file mode 100644 index 00000000..e69de29b diff --git a/docs/Action-Nodes-Decorators.md b/docs/Action-Nodes-Decorators.md new file mode 100644 index 00000000..88a150cb --- /dev/null +++ b/docs/Action-Nodes-Decorators.md @@ -0,0 +1,74 @@ +# Actions and Decorators + +Actions and Decorators are what enables any entity to actually exhibit behavior - they are the 'final' nodes which make an entity do things, and as such will be, alongside with the actual behavior trees, the parts of the Behavior API most useful to someone wishing to give its entity behavior. + +## Class Structure + +Action and Decorator nodes are implemented by the `ActionNode` and `DecoratorNode` classes, respectively. +Both implement the common `BehaviorNode` interface. + +An `ActionNode` is a leaf node and thus has no children + +A `DecoratorNode` has strictly one child. + +What is important to note is, `ActionNode` and `DecoratorNode` both use an associated `Action` to do their actual work. +For every class with a `@BehaviorAction` annotation, a corresponding ActionNode or DecoratorNode is created, using the specified `Action` class as the action which provides the functionality (and using the `name` specified in the annotation to identify the node in the prefab files). + +This means that in order to create a new Action or Decorator, typically _you do not want to create a new Node, but create an `Action` instead._ + +> [!NOTE|label:Managing State on Actions and Decorators] +> +> In order to save substantially on memory and some performance, every ActionNode and DecoratorNode is created only once for a given behavior tree - these nodes are shared by all Actors running the same tree. +> This means that **storing stateful information in the Action itself is a terrible idea!** +> +> In order to store and read state information, access the `Actor`'s `dataMap` instead, using the Action's `getId()` as an index. + +## `Action` and the `@BehaviorAction` annotation + +In order to create a new Action or Decorator for use in your behavior trees, you want to create a new class which implements the `Action` interface - extending `BaseAction` is the best way, as you can only focus on the functional parts of the action. + +In order for your `Action` to be discovered and loaded by the Behavior system, you need to annotate the class with the `@BehaviorAction` annotation. The format is: + +```java +@BehaviorAction(name = "") +``` + +and if the `Action` is supposed to be used in a Decorator, you add the `isDecorator` parameter: + +```java +@BehaviorAction(name = "An example of a behavior tree. + +Behavior trees are composed of different _nodes_, which determine if the behavior will be performed sequentially, or if it will be subject to any conditions. +The illustration above has _sequential_ nodes (right arrows), determining that everything below them will happen in a sequence (from left to right), and _condition_ nodes (question marks), determining that everything below them will happen (in sequence) only if a determined condition is satisfied. + +In Terasology, nodes are objects implementing the `TreeNode` interface. +There are composite nodes, action nodes, and decorators, but in an effort not to duplicate information too much, see [Tree Nodes](Tree-Nodes) to learn about the `TreeNode` interface in detail. + +Every `Actor` instance (see description below) has an associated `Interpreter`. +That interpreter uses a `BehaviorTreeRunner` (currently `DefaultBehaviorTreeRunner` as we aren't using the bytecode/ASM parts of the system) to work on the given tree - there is a `BehaviorTreeRunner` for every given Actor. +What's important is the `BehaviorTree` is a data class; it provides the underlying tree data, but it's shared between Actors, using the Interpreter/BehaviorTreeRunner combo. + +Both `BehaviorTree` and `Interpreter` can also be instantiated and assigned to an entity during gameplay (for example, when entities join a group and must adopt a different behavior). +In this case, the `BehaviorTree` instance is replaced by a new one, while the `Interpreter` can be created as a new instance or it can be replaced by another existing instance (this is particularly important in cases where an entity must not only assume the new behavior but also have its state placed in a specific point within the behavior tree). + +## Actor + +The Actor is a decorated Entity, a class that facilitates adds Behavior related functionality to a given Entity. +It represents an entity with a behavior. + +Important parts of the Actor class: + +- `Actor(EntityRef)` constructor - an Actor can only be constructed over a given Entity. +- `getEntity()` - returns the underlying entity. +- `getComponent()`, `getComponentField()`, `hasComponent()` - QoL methods providing easier access to some parts of the underlying entity. +- `save(Component component)` - assigns a component to the current Actor. This method is used when new components are assigned to the Actor, or in some cases when existing components are modified. + +Other important parts of the Actor class are: + +- `Map dataMap` + + _Used by every Behavior Node to manipulate its stateful information, so the Nodes themselves can be stateless/reusable. + The `id` arguments used in its related `getValue()` and `setValue()` methods are the tree-unique IDs of the Nodes._ + +- `Map blackboard` + + _Used to facilitate inter-node communication. + While in `dataMap` every node has its own little corner where it stores its info, `blackboard` is the shared space where nodes can co-ordinate any higher level stateful goals._ + +## Assets + +Behaviors are JSON-like files that describe a behavior tree, containing pre-defined elements (nodes) and actions associated with these nodes. +These files (`.behavior`) are located in the `assets/behaviors` folder of each module. + +Each entity can have a behavior component included in its `.prefab` file as: + +```json +"Behavior" : { + "tree" : ":" +} +``` + +Where `` refers to the name of the behavior, and `` refers to the module in which the behavior is defined. You can use any pre-made behavior existing in another module. If you use the `stray` behavior from the Behaviors module, for example, your `.prefab` behavior entry will be: + +```json +"Behavior" : { + "tree" : "Behaviors:stray" +} +``` + +> [!NOTE] +> Although you can omit the `` prefix for behaviors defined in the same module, it is good practice to **always** use the fully qualified name. +> +> This makes it easier to extract and move behaviors to different modules, and it also avoids confusion between behaviors of similar or identical names from different modules. + +A curated list of pre-made behaviors can be found [here](Pre-made-Behaviors-and-Nodes). + +## GUI Editor + +Behavior trees can also be created or edited through the use of the Behavior GUI editor. +The GUI editor is currently unstable, but its latest version can be accessed in-game through the F5 key. + +> [!NOTE] +> The UI editor is in a highly experimental state. +> We recommend that you edit your `.behavior` files directly in a text editor of your choice. diff --git a/docs/Building-a-Behavior-Tree.md b/docs/Building-a-Behavior-Tree.md new file mode 100644 index 00000000..855fee8c --- /dev/null +++ b/docs/Building-a-Behavior-Tree.md @@ -0,0 +1,114 @@ +# Creating a Behavior Tree + +Any given behavior tree is specified as a JSON-like asset in the module's `assets/behaviors` folder, with the `.behavior` extension: + +Behavior files are part of a module's assets. + +To create a new tree, just create a `.behavior` file in your module's `assets/behaviors` folder and open it in your favorite text editor. + +## Tree file structure + +The actual tree definition files have a very simple structure: essentially, the `.behavior` file only represents the definition of the root (top-most) TreeNode, with all of its children/arguments, recursively. +As an example, this is how the file `still.behavior` (originally from the `WildAnimalsMadness` module) is structured: + +```yaml +{ + sequence:[ + { + animation : { + play: "engine:Stand.animationPool", + loop: "engine:Stand.animationPool" + } + }, + { + sleep : { + time : 3 + } + } + ] +} +``` + +### Nodes - the building blocks + +Every TreeNode is required to have a `name`. +That name is pre-defined for the logic / flow control nodes and some special nodes - a reference of which is [here](https://github.com/Terasology/Behaviors/wiki/Control-Flow-Nodes) - and every Action and Decorator node has its name specified by the `name` field in its `BehaviorAction` annotation - more on that [here](Tree-Nodes). + +This `name` represents any and every Node in the JSON defining the tree. + +#### Simple Nodes, Actions + +A simple node with no arguments - which includes most Actions - is represented only by writing down its name: + +```yaml + +``` + +#### Nodes with arguments + +A node which needs some arguments to be specified needs to be written down as an object: + +```yaml +{ : { argument-1: value-1, ? <..> + argument-n + : value-n } } +``` + +In the case of **Decorators** (nodes with strictly 1 child), the child is provided as any other argument, in the form + +```yaml +child: +``` + +where `` can be any arbitrary node, including composite nodes or other Decorators. + +#### Composite Nodes + +A Composite (multiple-children) node is represented using an array: + +```yaml +{ : [ + , + , + <..> + , + ] } +``` + +```yaml +success +``` + +> [!NOTE|label:A note on quotes and JSON] +> While the JSON standard disallows keys not wrapped in double quotations, our GSON / deserialization implementation for the most part doesn't care about it - at least in terms of behavior tree files. +> This means that this: +> +> ```yaml +> { sequence: [{ timer: { time: 5 } }, { log: { message: Hello! } }] } +> ``` +> +> is virtually identical to this: +> +> ```json +> { +> "sequence": [ +> { +> "timer": {"time": 5} +> }, +> { +> "log": {"message": "Hello!"} +> } +> ] +> } +> ``` +> +> The variant without quotes is a bit more readable and less 'boilerplate-y', but both variants are possible. +> +> _However_, the canonical - quote-infested - version is the only one 100% officially supported, so if you run into issues with the tree file loading, it is a good idea to try if the issue persists with a canonical JSON version of the same tree. +> +> One very handy tool for converting the terse version into canonical JSON is [YAML Parser](http://yaml-online-parser.appspot.com/) - simply paste your tree definition into the left pane, and it spits out canonical JSON on the right. +> It also catches many formatting / syntax errors (but not all, as YAML is a superset of JSON). + +## Examples + +You can find examples of behavior trees in action [here](Pre-made-Behaviors-and-Nodes). diff --git a/docs/Case-Study.md b/docs/Case-Study.md new file mode 100644 index 00000000..b0e4fc25 --- /dev/null +++ b/docs/Case-Study.md @@ -0,0 +1,294 @@ +# Case Study + +This page details the process of creating a new module with creatures, behaviors, and groups. +You should understand how Terasology's behavior system works - it is explained [here](big-picture). +All source code for the present tutorial is available in the [TutorialGroups](https://github.com/Terasology/TutorialGroups/) module. + +## Context + +We are going to show how to create a module from scratch, but using existing creatures and behaviors as a basis. + +**This is a long tutorial as we will explore all steps of the process in detail**. + +The idea is to show not only how behaviors and groups can be used together, but how to reuse existing code in new modules. +For this reason, we will use existing code as much as possible - be sure to follow the links as they appear. + +Our objective is to create a group of creatures with the same behavior. +We will use a variant of deer from the `WildAnimals` module for that. +Also, for this case study: + +- We will use existing creatures from the [WildAnimals module](https://github.com/Terasology/WildAnimals/) +- We assume that you already prepared your development workspace, as described [here](https://github.com/MovingBlocks/Terasology/wiki/Contributor-Quick-Start) +- We are creating a new module in this tutorial, but you can also [use an existing module as a basis](https://github.com/MovingBlocks/Terasology/wiki/Developing-Modules). +- Our module depends on other existing modules. + +If you don't know how to include other modules as dependencies of a new one, please check [this page](https://github.com/MovingBlocks/Terasology/wiki/Module-Dependencies). + +## Getting started + +We will create a new module called `TutorialGroups` and add `Behaviors` and `WildAnimals` as dependencies. +Your `module.txt` file should look like this: + +```json +{ + "id" : "TutorialGroups", + "version" : "0.1.0-SNAPSHOT", + "author" : "casals", + "displayName" : "TutorialGroups", + "description" : "Tutorial module for the wiki case study", + "dependencies" : [ + {"id" : "Behaviors", "minVersion" : "0.2.0"}, + { "id": "WildAnimals", "minVersion": "0.2.0" } + ], + "serverSideOnly" : false +} + +``` + +Let us also create a new entity to use in our tests. +Since our module depends on `WildAnimals`, we can use any of the existing deer as a basis for our new entity (if you don't know how entities can be described by prefabs, please check [this link](https://github.com/MovingBlocks/Terasology/wiki/Entity-System-Architecture#prefabs)). +We will create an entity called `testDeer`, based on the `greenDeer` prefab. +For that, we just need to create a file named `testDeer.prefab` in our `assets/prefabs` folder, with the following contents: + +```json +{ + "parent" : "greenDeer" +} +``` + +This will allow our `testDeer` to inherit all base components from `greenDeer`. + +## Defining a behavior + +There are several different behaviors that we could add to our deer. +Usually, we would just include a `Behavior` component in the entity prefab, as shown [here](Quick-Start#assigning-a-behavior-to-an-entity) (you can learn how to create your behaviors [here](Step-By-Step-Tutorial)). +However, since we want a broad example of how to use behaviors and groups, let's assume the following situation: + +- We want our deer to be assigned to groups as soon as they are spawned; +- We want our deer to idly stray around until they are attacked by a player (in which case they flee away); and +- We want our deer to display group coordination: if one deer is attacked, all deer in the group should flee away from the group. + +If we consider only the first two items of our behavior checklist, there's already a behavior that does that - it is called `critter`, and it is defined in the `Behaviors` module. +Let us take a closer look at the `critter.behavior` file: + +```json +{ + dynamic: [ + { + guard: { + componentPresent: "Behaviors:Fleeing", + child: { + sequence: [ + check_flee_stop, + { + lookup: { + tree: "Behaviors:flee" + } + } + ] + } + } + }, + { + lookup: { + tree: "Behaviors:stray" + } + } + + ] +} +``` + +The behavior tree described in this file can be interpreted as: + +- There is a dynamic selector on the top of the tree that constantly re-evaluates all children that previously returned `FAILURE` with each tick; +- The first sub-node checks if the entity possesses a component called `Fleeing`, in which case it executes an action (`check_flee_stop`) and a nested behavior tree (`Behaviors:flee`); +- The second sub-node calls another nested behavior tree (`Behaviors:stray`). + +You can read more about each of these node types [here](Control-Flow-Nodes). +The nested sub-trees are pretty descriptive in what they do: the first one is composed by a set of nodes and actions that makes the entity to flee away from whoever is causing them damage, and the second one just establishes a straying behavior. +Also, the `check_flee_stop` action is implemented in the `Behaviors` module by the `CheckFleeStopAction`, and its goal is to determine if the damage received came from a player (*instigator*), thus determining if the entity should flee or not. + +Note that due to the dynamic node selector this tree will be re-evaluated every time it's determined that the entity should **not** flee (in which case the action returns a `FAILURE`) status. +However, for this check to happen, the entity must possess the `Fleeing` component. +Now - let's look at the original `deer` prefab (used as a basis for all deer in the `WildAnimals` module: + +```json +{ + "skeletalmesh" : { + "mesh" : "deer", + "heightOffset" : -0.8, + "material" : "deerkin", + "animation" : "deerIdle", + "loop" : true + }, + "Behavior" : { + "tree" : "Behaviors:critter" + }, + "FleeOnHit" : { + "minDistance" : 5 + }, +//... +} +``` + +Observe that the prefab does not contain any reference to a component named `Fleeing` - however, it contains a component called `FleeOnHit`, which seems related to what we need. +Also - it is important to notice that this prefab was defined in the `WildAnimals` module, but there are no references to any component called `FleeOnHit`. +This happens because `WildAnimals` also depends on the module `Behaviors`; when your module depends on another one, you can access all of its components and assets. +In the case of assets, you need to specify its module of origin (as in `Behaviors:stray`), but components can be seamlessly referenced and used in your prefabs. + +With that in mind, let's go back to the `Behaviors` module and take a closer look at the `FleeOnHit` component. +Its implementation (`FleeOnHitComponent` class) is pretty simple: it defines a minimum safe distance to be maintained from the aggressor, and a speed multiplier parameter used to set a default running speed when fleeing. +This component is used by a system implemented by `BehaviorsEventSystem`: + +```java +@RegisterSystem(RegisterMode.AUTHORITY) +public class BehaviorsEventSystem extends BaseComponentSystem { + + @In + private Time time; + + @ReceiveEvent(components = FleeOnHitComponent.class) + public void onDamage(OnDamagedEvent event, EntityRef entity) { + + // Make entity flee + FleeingComponent fleeingComponent = new FleeingComponent(); + fleeingComponent.instigator = event.getInstigator(); + fleeingComponent.minDistance = entity.getComponent(FleeOnHitComponent.class).minDistance; + entity.saveComponent(fleeingComponent); + + // Increase speed by multiplier factor + CharacterMovementComponent characterMovementComponent = entity.getComponent(CharacterMovementComponent.class); + characterMovementComponent.speedMultiplier = entity.getComponent(FleeOnHitComponent.class).speedMultiplier; + entity.saveComponent(characterMovementComponent); + + } +//... +} +``` + +There are a few things going on this system. +We won't explore how events, systems, and components work together at this moment, but you can learn more about the Entity System architecture used in Terasology [here](https://github.com/MovingBlocks/Terasology/wiki/Entity-System-Architecture). +Let's take a closer look at the `onDamage` method (which defines what happens to an entity possessing the `FleeOnHit` component once it receives damage): + +- When the entity is damaged, the system creates a new `Fleeing` component and attaches it to the entity; + - The new component possesses relevant information about who caused the damaged (which is used later, as we saw before); +- The entity's speed is altered according to the speed multiplier defined in the `FleeOnHit` component. + +This pretty much solves what we need in terms of behavior, but we still need to make all deer in the group to flee if one of them is attacked. +At the same time, the fleeing behavior can be the same one already implemented in the `Behaviors` module (we just need to attach the group conditions). +That means we need: + +- A way of identifying our group; and +- A way to make all entities within the group to flee if one of them is attacked. + +Groups are, in a nutshell, an easy manner of identifying and handling multiple entities - you can read more about it [here](Groups). +For now, let's define that our group will be called `wisedeer`. +As we said before, we want our deer to belong to this group as soon as they are spawned - so we will amend our `testDeer.prefab` file to include this information. +We also want our deer to have a *slightly different* fleeing behavior from the one we saw before - but we have already seen a good strategy on processing a damage event, so let's use that. +We will also create a modified component called `GroupFleeOnHit` - it's pretty much the same as the original, but we want to take advantage of the existing implementation without interfering with other modules or behaviors using the same component. +Also, it's a great opportunity to add new characteristics. + +All things considered, we will need: + +- A new implementation of the modified `GroupFleeOnHit` component; and +- A system implementation, similar to the `BehaviorsEventSystem`, to process what happens in case of damage. + +Note that we can assign behaviors to entities either in their prefabs, or - if we are using groups - in our group asset (another JSON-like file). +We want to keep this tutorial as simple as possible, so we won't use any group assets at this point - but you can read more about them in the [Groups wiki page](Groups). + +At this point, it is important to notice that there is a reason why we are using the `greenDeer` as our basis. +All RGB deer in the `WildAnimals` module were built to be used as examples in tutorials; in particular, the `greenDeer` does not possess the `FleeOnHit` component. +This is important since the `GroupFleeOnHit` component exists so we can reuse as much code as possible (including the original `critter` behavior and `Fleeing` component). +In the case an entity possessed both components, we might have conflicting scenarios caused by different superposing settings (such as the speed multiplier). +We could also implement a new behavior from scratch, of course - but this case is already covered [here](Step-By-Step-Tutorial), and we don't want this tutorial to get repetitive. + +## Implementation + +With all the considerations above, our new `testDeer.prefab` file should look like this: + +```json +{ + "parent" : "greenDeer", + "Behavior" : { + "tree" : "Behaviors:critter" + }, + "GroupFleeOnHit" : { + "minDistance" : 5 + }, + "GroupTag" : { + "groups" : [ "wisedeer" ] + } +} +``` + +We will also need two new classes for our new component and system, respectively. +Let's create them in two different packages: + +#### `GroupFleeOnHitComponent`: + +```java +package org.terasology.behaviors.components; + +import org.terasology.entitySystem.Component; + +/** + * If this component is attached to an NPC entity it will exhibit the flee-on-hit behavior + * When hit, the NPC will run with a speed of `speedMultiplier`*normalSpeed + * till it is at a safe `minDistance` from the damage inflicter- `instigator`. + * When it reaches a safe distance the instigator is set to null. This component uses + * @see FleeOnHitComponent as a reference/basis. + */ +public class GroupFleeOnHitComponent implements Component { + /* Minimum distance from instigator after which the NPC will stop 'flee'ing */ + public float minDistance = 10f; + /* Speed factor by which flee speed increases */ + public float speedMultiplier = 1.2f; +} +``` + +#### `GroupBehaviorsEventSystem`: + +```java +package org.terasology.behaviors.system; +///import ... +/* + * Listens for damage events and responds according to the group behavior desired + */ +@RegisterSystem(RegisterMode.AUTHORITY) +public class GroupBehaviorsEventSystem extends BaseComponentSystem { + + @In + private Time time; + @In + private EntityManager entityManager; + + @ReceiveEvent(components = GroupFleeOnHitComponent.class) + public void onDamage(OnDamagedEvent event, EntityRef entity) { + + //Get all entities belonging to the 'wisedeer' group: + for (EntityRef entityRef : entityManager.getEntitiesWith(GroupTagComponent.class)) { + if (entityRef.getComponent(GroupTagComponent.class).groups.contains("wisedeer")) { + // Make entity flee + FleeingComponent fleeingComponent = new FleeingComponent(); + fleeingComponent.instigator = event.getInstigator(); + fleeingComponent.minDistance = entityRef.getComponent(GroupFleeOnHitComponent.class).minDistance; + entityRef.saveComponent(fleeingComponent); + + // Increase speed by multiplier factor + CharacterMovementComponent characterMovementComponent = entityRef.getComponent(CharacterMovementComponent.class); + characterMovementComponent.speedMultiplier = entityRef.getComponent(GroupFleeOnHitComponent.class).speedMultiplier; + entityRef.saveComponent(characterMovementComponent); + } + } + } +} +``` + +Observe that there is one difference in our system when compared to the original `BehaviorsEventSystem` class: it listens to damage events according to the existence of our new component, and then assigns a new `Fleeing` component to each of the entities belonging to the group. + +## Conclusion + +In this tutorial, we showed how to reuse creatures and behaviors from other modules to create your own group of creatures. +Learning about all the different mechanisms in Terasology can be challenging, especially if this is your first time working with this kind of architecture. +There are many other different manners of using behaviors and groups; besides the links and modules used here, we recommend that you check the [WildAnimalsMadness](https://github.com/Terasology/WildAnimalsMadness/) module. diff --git a/docs/Control-Flow-Nodes.md b/docs/Control-Flow-Nodes.md new file mode 100644 index 00000000..8c361048 --- /dev/null +++ b/docs/Control-Flow-Nodes.md @@ -0,0 +1,187 @@ +# Control Flow Nodes + +The control flow (logic) nodes are the building blocks of any behavior tree. +They provide the tools necessary to do many kinds of logic - run a node `n` times, run a given node only if the node before it succeeded, run nodes in parallel, run a node only for a given amount of time, etc. + +> [!NOTE] +> The term used to reference a node in behavior definitions is usually derived from the node name, for instance +> +> primary name: **DynamicSelector** +> technical name: `dynamic` (used in the behavior files) + +Here's a reference of the logic nodes with their respective functions: + +- [Control Flow Nodes](#control-flow-nodes) + - [Special nodes](#special-nodes) + - [Lookup `lookup`](#lookup-lookup) + - [Log `log`](#log-log) + - [Composite nodes](#composite-nodes) + - [Sequence `sequence`](#sequence-sequence) + - [Selector `selector`](#selector-selector) + - [DynamicSelector `dynamic`](#dynamicselector-dynamic) + - [Parallel `parallel`](#parallel-parallel) + - [Decorator nodes](#decorator-nodes) + - [Counter `counter`](#counter-counter) + - [Invert `invert`](#invert-invert) + - [Loop `loop`](#loop-loop) + - [Timeout `timeout`](#timeout-timeout) + +## Special nodes + +### Lookup `lookup` + +'Looks up' and runs a behavior tree. + +#### Parameters: + +- `tree` : the requested tree, in the form `':treeName'` + +`SUCCESS`: when the tree finishes with `SUCCESS`. + +`RUNNING`: if the tree is still `RUNNING` + +`FAILURE`: when the tree finishes with `FAILURE`. + +### Log `log` + +Logs a message + +Example: + +```js +sequence: [ + { + log: { + message: "walk to target" + } + }, + //... +] +``` + +## Composite nodes + +Composite nodes are nodes with more than one child - essential in various aspects of tree building. + +If you want to perform a series of actions that each depend on the previous ones succeeding - like a chain - a [Sequence](#sequence-sequence) will be useful. + +If you want to have conditional logic that selects between different behavior branches based on some conditions, a [DynamicSelector](#dynamicselector-dynamic) is recommended. + +If you want to run different branches in parallel, use the [Parallel](#parallel-parallel) node. + +Each of these nodes takes their children in arguments in this form: + +```yaml +{ : [, , <...>, ] } +``` + +### Sequence `sequence` + +Evaluates the children one by one, left to right. +Once a child finishes with `SUCCESS`, starts the next child. + +`SUCCESS`: when all children finished with `SUCCESS`. + +`FAILURE`: as soon as a child finishes with `FAILURE`. + +### Selector `selector` + +Evaluates the children one by one, until a child returns `SUCCESS`. +When a child finishes with `FAILURE`, evaluates the next in line. +If a child is `RUNNING`, doesn't re-evaluate previous children for state changes - until the Selector returns and is run again from the start. +If you want the dynamic re-evaluation, use [DynamicSelector](#dynamicselector-dynamic). + +`SUCCESS`: as soon as a child finishes with `SUCCESS`. + +`FAILURE`: when all children finished with `FAILURE`. + +### DynamicSelector `dynamic` + +Works like a Selector, but with each tick re-evaluates all children that have previously returned `FAILURE` or are currently `RUNNING`, making it useful for branching logic, when the top-level children are condition nodes of some description. + +More on this here: [Responding to outside changes](Responding-to-Outside-Changes) + +`SUCCESS`: as soon as a child finishes with `SUCCESS`. + +`FAILURE`: when all children finished with `FAILURE`. + +### Parallel `parallel` + +All children are evaluated in parallel. + +`SUCCESS`: when all children finished with `SUCCESS`. + +`FAILURE`: as soon as a child finishes with `FAILURE`. + +## Decorator nodes + +Decorator nodes have exactly one child - useful to add functionality to existing nodes, modify what a node returns, etc. + +Every Decorator takes its child as a `child: ` argument, e.g. + +```yaml +{ + : { + child: +} +``` + +Other arguments can of course be specified in normal JSON fashion. +Keep in mind simple children can be defined without the `{}` - e.g. + +```yaml +child: success +``` + +is a completely valid definition. + +### Counter `counter` + +Runs the child node a set number of times. + +#### Parameters + +- `count` : int, the number of times the child should be executed + +`SUCCESS`: when the child finishes with `SUCCESS` the n-th time in a row. + +`FAILURE`: as soon as the child finishes with `FAILURE`. + +### Invert `invert` + +Returns the inverse of the state returned by the child. +Doesn't change `RUNNING`. + +`SUCCESS`: when the child finishes with `FAILURE`. + +`FAILURE`: when the child finishes with `SUCCESS`. + +### Loop `loop` + +Repeats the child node forever. Useful when controlled by overarching logic, else the tree can get stuck. + +`RUNNING`: Forever. + +### Timeout `timeout` + +Runs the child (decorated node) for a set amount of time. +Can be used without specifying a child - that way, it will only serve as a 'pause' - +it'll return `RUNNING` for the duration specified in its argument. + +#### Parameters + +- `time` - float, the time to use for the timer in seconds (e.g. `time: 10.0`). + +Without child: + +`RUNNING`: while the timer is running. + +`SUCCESS`: as soon as timer ended. + +With child: + +`RUNNING`: while the child is `RUNNING`. + +`SUCCESS`: when the child finishes with `SUCCESS`. + +`FAILURE`: when the child finishes with `FAILURE`. diff --git a/docs/Groups.md b/docs/Groups.md new file mode 100644 index 00000000..303c7a0e --- /dev/null +++ b/docs/Groups.md @@ -0,0 +1,95 @@ +# Groups + +Here you can find some information about Groups, and how they are used in conjunction with Behaviors. +To understand Groups, however, it is important to consider + +
    +
  1. how collective behaviors can be manifested, and +
  2. what are scenarios where groups can be used with behaviors. +
+ +It is important that you have a basic comprehension of how the behavior system works (especially the concept of behavior trees and associated states); if you didn't do it yet, please see the [Big Picture](Big-Picture) overview. + +## Scenarios + +There are different ways to look at collective behaviors, but in a general manner, we can classify it from the _coordination_ perspective (you can learn more about this [here](https://casals.io/code/gsoc-reaching-first-milestone/)). +From the game perspective, let us consider three different scenarios where an entity joins a group: + +* Scenario 1: Entities that join a group but are independent in terms of behavior (even if they have the same behavior tree - which may not be the case). + +* Scenario 2: Entities that join a group and have the same behavior tree, and they have to be _somewhat_ coordinated. A typical illustration is a group where only one of the members perceives an event, but all group members react to it. Their reactions, however, are processed individually. + +* Scenario 3: Entities that join a group and the same behavior tree, and they _must_ act the same way. In this scenario, the entities completely lose their autonomy, and their behavior is perfectly synchronized. + +You can read more about the different group behavior scenarios [here](https://casals.io/code/gsoc-reaching-second-milestone/). + +## Implementation + +In Terasology, the group structure is implemented in a manner that it can cover all three scenarios described above. + +### Assets + +Similarly to behaviors, a group is described by JSON-like files (`.group`) are located in the `assets/groups` folder of each module: + +Groups as part of a module's assets. + +A `.group` file describes the characteristics of a group as: + +- `groupLabel`: the unique group identifier. +- `needsHive`: flags the need for a _hivemind_ structure (when group members need to behave in unison, like in Scenario 3 described above). +- `behavior`: the name of the behavior tree used by the group (trees from other modules can be used as long as they are listed as dependencies). + +This structure is represented within the file as: + +```yaml +{ + "groupLabel": "", + "needsHive": "", + "behavior": "" +} +``` + +### Components + +There are two main components used by Groups: `GroupTag` and `GroupMind`. The `GroupTag` component is used to identify an entity as part of a labeled group. +It can be inserted in an entity's prefab file so that every time an instance of that entity is spawned in the game it will already be marked as belonging to the same group: + +```yaml +"GroupTag" : { + "groups" : [ "" ] + } +``` + +Observe that the `groups` component field is an array. +This is because the same entity can belong to many groups at the same level; the logic behind how the behavior inherited from each group will be enforced is handled at the system level. + +This component possesses two other fields, meant to be used in specific scenarios: `backupBT`, which stores an instance of a behavior tree object, and `backupRunningState`, which stores a behavior tree interpreter associated with `backupBT`. +Please check the Usage section below to see how they are meant to be used. + +The `GroupMind` component complements `GroupTag` in cases where there's the need for a unison behavior by all entities belonging to a group (please see Scenario 3 above). +It possesses three distinct fields: + +- `groupLabel`: the unique group identifier with which the component will be associated. +- `behavior`: the name of the behavior tree used by the group (trees from other modules can be used as long as they are listed as dependencies). +- `groupMembers`: a set containing the identifiers for each of the entities belonging to the group. + +This last field exists because, in scenarios that require `GroupMind`, there is a super-entity that manages all of the other entities within the group (this is better exemplified in the Usages section below). + +### Collective Behavior System + +Establishing a unison behavior also requires that the behavior trees of all entities within the group have not only the same behavior tree but the same behavior state at all times. +For this reason, the `CollectiveBehaviorSystem` was implemented in the core package. +It allows the use of a `CollectiveInterpreter` that processes all the behavior trees at the same time, assuring that all entities from a group will have the same state at all times. + +## Usage + +Using the group components in Terasology means identifying which of the three scenarios described above is appropriate to your case, and applying the correspondent usage patterns - which are: + +- Scenario 1: in this case, entities belonging to a group only need to be identified as so. The group entities will then only use the `GroupTag` component, which will be updated whenever they join or leave a different group. + +- Scenario 2: in this case entities belonging to a group need to possess the same behavior tree, regardless of the reasons. The group entities will still only use the `GroupTag` component. However, when an entity joins a group, it might be necessary to preserve its original behavior tree and associated state. In that case, both are saved into the appropriate `GroupTag` fields (`backupBT` and `backupRunningState`, respectively). + +- Scenario 3: in this case entities belonging to a group need to behave in unison. This can be achieved by electing a leader within the group, or by creating an invisible super-entity that will determine the group behavior. Regardless of how it is created, the leader or super-entity will need the `GroupMind` component. + +You can also check the [step-by-step tutorial](Step-By-Step-Tutorial) for a quick overview of how to use groups in your module. +There is also a [case study](Case-Study) on creating a module and adding behavior to creatures in a group. diff --git a/docs/Pre-made-Behaviors-and-Nodes.md b/docs/Pre-made-Behaviors-and-Nodes.md new file mode 100644 index 00000000..d97cd7d5 --- /dev/null +++ b/docs/Pre-made-Behaviors-and-Nodes.md @@ -0,0 +1,120 @@ +# Behaviors and Nodes + +This is a curated list with some of the more specialized Nodes and Behaviors that are available out of the box in different modules. + +- [Behaviors and Nodes](#behaviors-and-nodes) + - [Behaviors](#behaviors) + - [DoRandomMove](#dorandommove) + - [Stray](#stray) + - [Follow](#follow) + - [AttackFollowedEntity](#attackfollowedentity) + - [Hostile](#hostile) + - [Flee](#flee) + - [Nodes](#nodes) + - [Control Nodes](#control-nodes) + - [Movement Nodes](#movement-nodes) + - [Sound Nodes](#sound-nodes) + +## Behaviors + +You can find the premade behavior files in [this folder](https://github.com/Terasology/Behaviors/tree/1635a7734e269bedc8d92387942d8dd1468f3430/assets/behaviors/common). + +Examples of these pre-made behaviors being used to create new creature behaviors can be found in [this folder](https://github.com/Terasology/Behaviors/tree/1635a7734e269bedc8d92387942d8dd1468f3430/assets/behaviors/creatures). + +### [DoRandomMove](https://github.com/Terasology/Behaviors/blob/1635a7734e269bedc8d92387942d8dd1468f3430/assets/behaviors/common/doRandomMove.behavior) + +Short, utilitarian tree. When ran, finds a nearby block and moves towards it. + +### [Stray](https://github.com/Terasology/Behaviors/blob/1635a7734e269bedc8d92387942d8dd1468f3430/assets/behaviors/common/stray.behavior) + +A basic tree for critters. The entity starts the Walk animation, executes the `do_random_move` tree, then waits a while in the Stand animation, then repeats. +Results in randomly wandering mobs. + +### [Follow](https://github.com/Terasology/Behaviors/blob/1635a7734e269bedc8d92387942d8dd1468f3430/assets/behaviors/common/follow.behavior) + +The entity finds the nearest player and moves towards them if they are within a minimum distance (using the [`set_target_to_followed_entity`](https://github.com/Terasology/Behaviors/blob/master/src/main/java/org/terasology/behaviors/actions/SetTargetToFollowedEntityAction.java)). + +### [AttackFollowedEntity](https://github.com/Terasology/Behaviors/blob/1635a7734e269bedc8d92387942d8dd1468f3430/assets/behaviors/common/attackFollowedEntity.behavior) + +The entity searches for a player to follow within a range. If it finds one, it attacks it using the [`damage_followed_entity`](https://github.com/Terasology/Behaviors/blob/master/src/main/java/org/terasology/behaviors/actions/DamageFollowedEntityAction.java) action. + +### [Hostile](https://github.com/Terasology/Behaviors/blob/1635a7734e269bedc8d92387942d8dd1468f3430/assets/behaviors/common/hostile.behavior) + +This behavior uses the `AttackFollowedEntity` behavior and the [`check_attack_stop`](https://github.com/Terasology/Behaviors/blob/1635a7734e269bedc8d92387942d8dd1468f3430/src/main/java/org/terasology/behaviors/actions/CheckAttackStopAction.java) action. If the player is out of the critter's range, it will stop attacking. + +### [Flee](https://github.com/Terasology/Behaviors/blob/1635a7734e269bedc8d92387942d8dd1468f3430/assets/behaviors/common/flee.behavior) + +The entity runs away from the player using the [`set_target_nearby_block_away_from_instigator`](https://github.com/Terasology/Behaviors/blob/master/src/main/java/org/terasology/behaviors/actions/SetTargetToNearbyBlockAwayFromInstigatorAction.java) action. A use for this might be if a critter is attacked, it might want to flee from its attacker. + +## Nodes + +These nodes can be found in [this folder](https://github.com/Terasology/Behaviors/tree/1635a7734e269bedc8d92387942d8dd1468f3430/assets/prefabs/behaviorNodes). + +### Control Nodes + +The `target` referred to in the following nodes is the `target` variable of the entity's `MinionMoveComponent`. + +#### SetTargetLocalPlayerNode + +Sets the target to the block the player is currently standing on. + +#### SetTargetToNearbyBlockNode + +Sets the target to a random reachable block near the entity. + +### Movement Nodes + +#### FindPathToNode + +Requests a path towards a block from the Pathfinding system. This Path will be saved as `path` in the entity's MinionMoveComponent. + +`RUNNING` while the path is being searched for + +`SUCCESS` once a path has been found + +`FAILURE` if a path can't be found + +#### MoveToNode + +Moves to the target specified in MinionMoveComponent. + +`RUNNING` while the actor is moving towards the target +`SUCCESS` when the target is reached + +#### MoveAlongPathNode + +Moves along the `path`. + +#### JumpNode + +Triggers a single jump into the air. + +`RUNNING` while the jump is in progress + +`SUCCESS` once the actor lands + +### Sound Nodes + +#### `PlaySound` + +_Properties_: `sound`, `volume` + +Plays a sound (wow, really?) + +`RUNNING`: while the sound is playing + +`SUCCESS`: once sound ends playing + +`FAILURE`: otherwise + +#### `PlayMusic` + +_Properties_: `music` + +Starts playing music + +`RUNNING`: while music is playing + +`SUCCESS`: once the music ends playing + +`FAILURE`: otherwise diff --git a/docs/Quick-Start.md b/docs/Quick-Start.md new file mode 100644 index 00000000..64ec06b6 --- /dev/null +++ b/docs/Quick-Start.md @@ -0,0 +1,76 @@ +# Quick Start + +This page serves as a brief summary of the main points of the Behavior system. +The details of each part are detailed on their respective pages. + +For this tutorial, we'll assume you have an entity/creature you want to bring to life. +If you don't, check out our [asset system tutorial](https://github.com/Terasology/TutorialAssetSystem/wiki/Add-New-Creature) to learn how to create one. + +## Behavior trees + +Behavior trees are the structures used to describe the behavior of an entity within the game. +A behavior is a pre-defined set of actions performed by an entity, triggered by specific conditions or events. +Behaviors can be related to movement (animals wandering in an open field) or more complex actions (searching for water sources to fulfill a specific need). + +In Terasology, a behavior tree is described in a JSON-like file, which contains pre-defined elements (nodes) and actions associated with these nodes. +These files (`.behavior`) are located in the `assets/behaviors` folder of each module. +Behavior trees are composed of objects implementing the `TreeNode` interface. + +> [!WARNING] +> Note, that the syntax of behavior tree files is **not valid JSON** in all cases. + +To learn more about the structure of behavior trees, please see [Tree Nodes](Tree-Nodes). + +To see how a behavior tree can respond to events and changes in the entity, see [Responding to Outside Changes](Responding-to-Outside-Changes). + +If you want to create your own Behavior (`.behavior`) file, you can learn how to do it [here](Building-A-Behavior-Tree). + +## Assigning a Behavior to an Entity + +To possess a behavior, an entity must have a `Behavior` component referring to an existing behavior tree. +To specify the behavior tree your entity will use, go into its `.prefab` file, and find (or create) the `Behavior` entry in the JSON. + +The correct format is: + +```json +"Behavior" : { + "tree" : ":" +} +``` + +You can use any pre-made behavior existing in another module. +If you use the `stray` behavior from the Behaviors module, for example, your `.prefab` behavior entry will be: + +```json +"Behavior" : { + "tree" : "Behaviors:stray" +} +``` + +> [!NOTE] +> Although you can omit the `` prefix for behaviors defined in the same module, it is good practice to **always** use the fully qualified name. +> +> This makes it easier to extract and move behaviors to different modules, and it also avoids confusion between behaviors of similar or identical names from different modules. + +A curated list of pre-made behaviors can be found [here](Pre-made-Behaviors-and-Nodes). + +## Groups + +Behaviors can also be used by groups of entities. +Similarly to behaviors, a group is described by JSON-like files (`.group`) are located in the `assets/groups` folder of each module. +Groups can be used in situations where the same behavior must be assigned to multiple entities at a time. For more details on groups, please see [Groups](Groups). + +## GUI editor + +Behavior trees can also be created or edited through the use of the Behavior GUI editor. +The GUI editor is currently unstable, but its latest version can be accessed in-game through the F5 key. + +> [!NOTE] +> The UI editor is in a highly experimental state. +> We recommend that you edit your `.behavior` files directly in a text editor of your choice. + +## Examples + +If you want to learn how to build your own behavior, please check the [Step-by-Step Tutorial](Step-By-Step-Tutorial). + +Also - if you want to start by learning how you can reuse existing code by modifying existing behaviors and adapting it to your scenario - there's a [case study](Case-Study) about it available. diff --git a/docs/README.md b/docs/README.md new file mode 120000 index 00000000..32d46ee8 --- /dev/null +++ b/docs/README.md @@ -0,0 +1 @@ +../README.md \ No newline at end of file diff --git a/docs/Responding-to-Outside-Changes.md b/docs/Responding-to-Outside-Changes.md new file mode 100644 index 00000000..6695a73f --- /dev/null +++ b/docs/Responding-to-Outside-Changes.md @@ -0,0 +1,107 @@ +# Responding to Outside Changes + +A recurring question in any AI implementation is how to handle outside changes - how to make the entity react upon being hit while it's patrolling, for example. + +## Selector and Dynamic Selector + +The `Selector` and `DynamicSelector` nodes are similar in function: they iterate through their children, running a child if it returns `RUNNING` or `SUCCESS`, but moving on and trying the next child if the original child returns `FAILURE`. +This allows the tree to prioritize some branches over others. + +The obvious use case is something like this, for an imaginary worker which can fight/run from danger, has to eat, and otherwise works on a job: + +```yaml +selector: [ensure-safe, ensure-not-hungry, work] +``` + +Where `ensure-safe` returns FAILURE if it doesn't make sense for it to run (entity is safe already), the selector moves on to `ensure-not-hungry`, etc. + +The differences between Selector and Dynamic Selector are in the way they handle nodes that have previously returned `FAILURE`: + +- plain ol' `Selector` moves on and forgets about it - not re-evaluating it until the control flow of the tree reaches the selector again at some point in the future. + This can be useful in certain Sequence-y situations, but can result in 'stubbornness' if used in conditional / branching logic trees, such as the example above. +- `DynamicSelector` instead re-evaluates every child that has returned `FAILURE` on every tick, ensuring if something changes (e.g. the worker in the example above becomes hungry), the appropriate action is taken instantly. + +## ConditionAction + +In order to branch behavior, we need a good way to tell whether something of interest is happening to the Entity. +This is where `ConditionAction` steps in. + +ConditionAction is a leaf node - it doesn't have any children. +Its `name` for tree prefabs is `condition`. +Its parameters allow you to check for 3 things: + +- `componentPresent` specifies a Component which needs to be present on the Entity in order for the condition to hold +- `componentAbsent` (you guessed it) specifies a Component which needs to be absent from the Entity in order for the condition to hold +- `values` - specifies an array of conditions that need to be true on the fields of the Component for the condition to hold. + - the format is: `[, , .. ]` where every condition is of this format: `type fieldName operator valueToCheckAgainst` + - The first parameter - `type` - has the following options: + - `V` - [V]alue - denotes the `valueToCheckAgainst` parameter is a plain value + - `F` - [F]ield - denotes the `valueToCheckAgainst` parameter is the name of another field in the component + - `N` - [N]one - denotes no `valueToCheckAgainst` is specified - useful in checks where a second value wouldn't be meaningful. + - Different data types support different operations specified by the `operator`: + - `< > <= >= = == != !` - numbers (float, int, double, long, short, etc.) + - `== != = !` - Strings and booleans + - `!` and `=` is just shorthand notation for `!=` and `==` respectively. + - `empty`, `nonEmpty`, `null` and `exists`: for use on nullable Objects (the `empty` checks are Collection specific) + - some examples: + - `["F currentHealth < maxHealth"]` checks whether the currentHealth field is under maxHealth, e.g. the entity is damaged. + - `["V isEnraged = false", "V enrageCooldown = 0"]` checks preconditions for a fictional 'Enrage' ability the actor might want to do. + - `["N enemiesInRange nonEmpty"]` - checks whether at least one enemy is in range (assuming the `enemiesInRange` field is a Collection) + +### Example usage: + +A `condition` will typically be used in a `sequence`. +In a sequence, if placed before some action nodes, it can ensure certain conditions were met before executing a further action. +Placing this encompassing `sequence` in a `dynamic` selector leads to easy branching behavior - the `condition` at the beginning of the sequence tells the tree whether to go further into the sequence or not. + +The below example shows a simple tree which checks whether the entity's health is under 15, if so, logs a message, otherwise moves on - in this case to a `running` node. + +```yaml +{ + dynamic: + [ + { + sequence: + [ + { + condition: + { + componentPresent: "Core:Health", + values: ["V currentHealth < 15"], + }, + }, + { log: { message: "I'm injured!" } }, + ], + }, + running, + ], +} +``` + +### Guard + +An special version of a `condition` is `guard`. Guard functions like a condition, but it is a Decorator, and the underlying condition logic decides whether the child gets run or not. +This can be handy for clarity with simpler branches - if you don't want `sequence`s for every little condition check. + +#### Example usage: + +A guard can be used on its own in a selector. This is the same example as the above, but using a `guard`. + +```yaml +{ + dynamic: + [ + { + guard: + { + componentPresent: "Core:Health", + values: ["V currentHealth < 15"], + child: { log: { message: "I'm injured!" } }, + }, + }, + running, + ], +} +``` + +Keep in mind that the `child` can be anything - an `action`, another `decorator`, a `lookup` node or even a whole complex tree. diff --git a/docs/Step-By-Step-Tutorial.md b/docs/Step-By-Step-Tutorial.md new file mode 100644 index 00000000..4bb3843a --- /dev/null +++ b/docs/Step-By-Step-Tutorial.md @@ -0,0 +1,247 @@ +# Step-by-Step Tutorial + +This page shows how to create a behavior from scratch. +It is highly advisable that you understand how Terasology's behavior system works - it is explained [here](big-picture). + +## Getting started + +If you are here, it means you want to assign a behavior to an entity or creature in the game. +We will not cover the basics of creating a new creature - you can find more about this subject in [this tutorial](https://github.com/Terasology/TutorialAssetSystem/wiki/Add-New-Creature). + +The first thing to do is to model what your creature is supposed to do. +Let's say that you want your creature to do the following: + +- Go from where it stands to another location; +- Stay at the new location for a couple of seconds; +- Do it again. + +You will (eventually) find that this is pretty much what the `stray` behavior does: the creature walks around the field, moving from one spot to another from time to time. +Now - assuming that you already know about Terasology's behavior system, you also know that we will need to represent this behavior as a _behavior tree_. +This is what it looks like: + + + +The right arrow in the picture represents a _sequence_ node, and the red containers represent the _actions_ that will be executed. +This is, of course, a very simplified view of our behavior tree. +For example, let's assume that you are using a creature that already possesses a movement-related component, such as the ones you'll find in the [Wild Animals module](https://github.com/Terasology/WildAnimals/). +In this case, in order to initiate/end the creature's movement, it is necessary to alter its speed: when the creature is moving, is possesses a speed greater than zero. +Similarly, when the creature stops its speed is set to zero. + +In the Wild Animals module, the creature's movement can be controlled through the `CharacterMovement` component. +Here's how it looks like in the creature's prefab (we are using the `deer.prefab` file as an example - you can find it in Wild Animals' asset folder): + +```json +"CharacterMovement" : { + "groundFriction" : 16, + "speedMultiplier" : 0.3, + "distanceBetweenFootsteps" : 0.2, + "distanceBetweenSwimStrokes" : 2.5, + "height" : 1.6, + "radius" : 0.3, + "jumpSpeed" : 12 +} +``` + +Observe that it contains a parameter called `speedMultiplier`. +Modifying this parameter is how we can control the character's speed: if we set it to zero, the base speed of the creature is multiplied by zero (so it stops). +If we set if to a value other than zero, the creature goes faster or slower, according to what we want to do. +For now, let's just say that we need to get the creature to a speed greater than zero when it starts moving, and then back to zero when it stops. +Now our behavior tree looks like this: + + + +Observe that we have two different actions here: + +- One action that changes the speed multiplier of the `CharacterMovement` component; and +- One action that actually tells the creature to move from one place to another. + +Part of the beauty of using behavior trees is that you can _reuse_ other existing behavior trees. +To illustrate that - and for the sake of simplicity - let's reuse an existing behavior tree associated with the movement action. +In the [Behaviors module](https://github.com/Terasology/Behaviors) there is a behavior tree that does exactly that: moves the creature from a spot to a new, random one. +This behavior tree is called `doRandomMove`. +So let's use it - the only requisite is that the `Behaviors` module is listed as a dependency of the module you are currently working on (check the [module development guide](https://github.com/MovingBlocks/Terasology/wiki/Developing-Modules) for more details on how to add dependencies in your modules). +Your new behavior tree should look like this: + + + +The blue box is the behavior tree that we are reusing from the `Behaviors` module. + +## Creating your behavior file + +Now that you already have your behavior tree, let's represent it using a `.behavior` file. +In the module you are working on, go to the assets/behaviors folder and create a file called `basicStray.behavior`. +For a quick reference, you can find more details on the structure of a `.behavior` file [here](Building-a-Behavior-Tree). +Open the newly created file in any text editor and - using the proper semantics - translate it to the used JSON-like format. +After editing, your file should look like this: + +```yaml +{ + + sequence : [ + { + change_speed : { speedMultiplier: 0.5 } + }, + { + lookup: { tree: "Behaviors:doRandomMove" } + } + }, + { + change_speed : { speedMultiplier: 0 } + }, + { + sleep : { + time : 2 + } + } + ] +} +``` + +...and that's about it - you have a new behavior. +Don't forget to include it in your creature's prefab: + +```yaml +"Behavior": { "tree": ":basicStray" } +``` + +## Actions + +It is true that the behavior file was already created - but what should you do about the actual, well, actions? In the case of moving the creature, we used an existing behavior tree, which uses actions that are already implemented, etc. +But there's still the matter of changing the speed multiplier in the `CharacterMovement` component. + +You can find more about developing within the Terasology environment [here](https://github.com/MovingBlocks/Terasology/wiki/Developing-Modules) - but for now, we only need to create an action. +After [setting up your development environment](https://github.com/MovingBlocks/Terasology/wiki/Preparing-an-Engine-Workspace): + +- Go to your source package folder; +- Create a sub-package (sub-folder) called `actions`; +- Create a new class called `ChangeSpeedAction`. + +If you created your module using `groovyw` (or if you are modifying an existing module), you should have something like: + + + +We won't go through all the development points of an action - you can check existing examples in different modules. +However, here are a few important points: + +- Any action must extend the `BaseAction` class, overriding the `modify` method to return the appropriate behavior state after its execution. +- The `BehaviorAction` annotation specifies the action name referred in the `.behavior` file. **They must be one and the same**, otherwise you will get a compilation error. +- Any action parameters used in the `.behavior` file must be declared as a private field in the class implementation. + +With that in mind, here's a simple implementation of the action `changeSpeed`: + +```java +@BehaviorAction(name = "change_speed") +public class ChangeSpeedAction extends BaseAction { + private float speedMultiplier; + + @Override + public void construct(Actor actor) { + if(actor.hasComponent(CharacterMovementComponent.class)) { + EntityRef entityRef = actor.getEntity(); + CharacterMovementComponent characterMovementComponent = entityRef.getComponent(CharacterMovementComponent.class); + characterMovementComponent.speedMultiplier = speedMultiplier; + entityRef.saveComponent(characterMovementComponent); + } + } + + @Override + public BehaviorState modify(Actor actor, BehaviorState result) { + return BehaviorState.SUCCESS; + } + +} +``` + +## Using Groups + +We can use our newly created behavior (or any existing other) with groups. +There are different behavioral scenarios where groups can be used - if you don't know how they work yet, please check [this page](Groups). + +### Creating groups + +First - let us consider that you just want to identify a group of entities. +You can do that either by pre-assigning a group to all entities of the same type, or you can do that in-game (according to a specific system logic). +In the case you want all entities of the same type to be identified as members of the same group, just include the `GroupTag` component in their `.prefab` file: + +```yaml +"GroupTag": { "groups": [""] } +``` + +Or - you can do it in your system logic: + +```java +for (EntityRef entityRef : entityCollectionFromYourCriteria) { + GroupTagComponent groupTag = new GroupTagComponent(); + groupTag.groupLabel = ""; + entityRef.saveComponent(groupTag); + + } +``` + +You can then retrieve all entities belonging to `` using the same `GroupTag` component: + +```java +for (EntityRef entityRef : entityManager.getEntitiesWith(GroupTagComponent.class)) { + if (entityRef.getComponent(GroupTagComponent.class).groups.contains("")) { + //do stuff + } + } +``` + +### Assigning group behavior + +Now that you have a group, let us assume that you want to assign your newly created `:basicStray` behavior to all members of this group. +Assuming that your entity does not have a previous behavior, the simplest way is to hard-code it in your system logic: + +```java +for (EntityRef entityRef : entityManager.getEntitiesWith(GroupTagComponent.class)) { + if (entityRef.getComponent(GroupTagComponent.class).groups.contains("")) { + BehaviorTree groupBT = assetManager.getAsset(":basicStray", BehaviorTree.class).get(); + + BehaviorComponent behaviorComponent = new BehaviorComponent(); + behaviorComponent.tree = groupBT; + behaviorComponent.interpreter = new Interpreter(new Actor(entityRef)); + behaviorComponent.interpreter.setTree(groupBT); + + entityRef.saveComponent(behaviorComponent); + + } + } +``` + +It might be the case, however, that our entity _has_ a previous behavior - and not only that, but you don't want to lose it (neither the behavior state associated with it). +You can save both the original entity's behavior and its state using the `GroupTag` component: + +```java +for (EntityRef entityRef : entityManager.getEntitiesWith(GroupTagComponent.class)) { + if (entityRef.getComponent(GroupTagComponent.class).groups.contains("")) { + //saving the original behavior + BehaviorComponent behaviorComponent = entityRef.getComponent(BehaviorComponent.class); + + GroupTagComponent groupTagComponent = entityRef.getComponent(GroupTagComponent.class); + + groupTagComponent.backupBT = behaviorComponent.tree; + groupTagComponent.backupRunningState = new Interpreter(behaviorComponent.interpreter); + entityRef.saveComponent(groupTagComponent); + + //assigning a new behavior + BehaviorTree groupBT = assetManager.getAsset(":basicStray", BehaviorTree.class).get(); + + behaviorComponent.tree = groupBT; + behaviorComponent.interpreter = new Interpreter(new Actor(entityRef)); + behaviorComponent.interpreter.setTree(groupBT); + + entityRef.saveComponent(behaviorComponent); + + } + } +``` + +It is important to notice that if you have multiple groups and related group behaviors, it would be a good idea to use `.group` files. +This will allow you to programatically assign different behaviors to different groups in your system logic. +For more information on how to create `.group` files please click [here](Groups). + +## Other examples + +There is a case study on creating a module and adding behavior to creatures in a group [here](Case-Study). Also - a complete example of using groups in different scenarios can be found in the [WildAnimalMadness](https://github.com/Terasology/WildAnimalsMadness/) module. +For more examples of behaviors used in modules, please check [our curated list](Pre-made-Behaviors-and-Nodes). diff --git a/docs/Tree-Nodes.md b/docs/Tree-Nodes.md new file mode 100644 index 00000000..3dd8cfd4 --- /dev/null +++ b/docs/Tree-Nodes.md @@ -0,0 +1,59 @@ +# Tree Nodes + +Every Behavior Tree is composed of many Nodes. +Here we shine some light on what the Nodes actually are. + +## The Behavior Node Interface + +Every Node implements the `BehaviorNode` interface. +Check the [Javadoc for BehaviorNode](https://jenkins.terasology.io/teraorg/job/Terasology/job/engine/job/develop/javadoc/org/terasology/engine/logic/behavior/core/BehaviorNode.html) for the full API specification. + +The important bits are: + +- `getName()` + + required for every node - this is what identifies the node for the BT / prefab system. + +- `construct(actor)` + + called when a Node begins executing - when it is reached in the tree. + +- `execute(actor)` + + called each time the node is executed - when the interpreter ticks and the tree is in a state where the node is executing. + +- `destruct(actor)` + + called when a node finishes executing. + +- child management methods + + These are self-explanatory, with children stored by index. + The implementation differs widely based on node type - more info can be found in their respective categories. + +## Node Types + +### Control Flow Nodes + +Control Flow nodes are responsible for the _logic_ parts of the behavior tree - they ensure some nodes are only run in a sequence, some run in parallel, some are run exactly _n_ amount of times, etc. + +Some `Decorator` nodes fall into this category (e.g. Timer, Inverter, Counter). + +More on control flow nodes here: [Control Flow Nodes](Control-Flow-Nodes). + + +## Action Nodes and Decorators + +Action and Decorator nodes are what most creators will be concerned with, in terms of creating new nodes. + +- Action nodes are leaves - nodes with no children. They are what enables the entity to have visible behavior traits - the actual actions the entity takes are defined in `Actions`. + +- Decorator nodes are nodes with strictly one child, usually an `ActionNode`, adding functionality to the child or modifying its return state. + +Actions and Decorators are loaded dynamically using the `@BehaviorAction` annotation. + +An in-depth look at Actions, Decorators and how to use them is here: [Action Nodes, Decorators](Action-Nodes-Decorators). + +> [!NOTE] +> In order to save on memory and some processor cycles, some nodes (notably Actions and Decorators) are created only once per behavior tree, and are stateless in nature - the state *needs to be stored at the Actor*. +> More on this [here](Action-Nodes-Decorators#important-note-on-state---if-youre-creating-your-own-actions-read). diff --git a/docs/_media/banner.png b/docs/_media/banner.png new file mode 100644 index 0000000000000000000000000000000000000000..b598bf41203fa9dd1a06c58696c09a28f32b455a GIT binary patch literal 1582165 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�#svnny?s;C(v8EgQEnjyC!XoL73H4Q!tu6-7FRGz86Pk-V(;VQ z7Z`Lrp^8V;U|B#`Q7;Ixb;JAQbVezJ`}cP!M3~PC>e&ptsE~V0GlGtf3SN5Y7;pXN zA+}2xi45Gl;VGdX)CC^2id>l_!qLme*xlVimq9sAKFGdCcxazXV=we=Vked0;{4pKi|6Uz~qEhGhALQD5Xz$5x_)obTao&JFo{D+=!nFISG#m zCDzr%j0p^7Tk9Ga(pRFXk*&_{!3r2BDMv8bgn*s8K^Xd)sJizIT)9-Uh}=~{R!}32 zs;AfxNcATj9nDT+R5TJnucbxAL-FWmB5kg?EO5}nK+x(VSjCNPkD#QeCSmd!78S5& z6e}M?hR-_(!nn_XU>BRX(O!7+`oL5CGJ=6{U;#)GQMU*@ z5Ch%B4DYIpR=65EZeYpiz{eq1GUI`gVOPZguUu1woBVBdWXvh&lBtiK7*1~xUi->T zoL?&5e)|EWUf?(H-NcQvzrbJr#jkO3p?LGn2RJ`}fQJ`5fC-za;Dr|mX2)FV`-V`)p*N&dT5XLaX6x8 zmrvQdmTXl|H_HH|g0fx)AUq(Os2=QV7Y#0Bh$KM1NH+?GAqeUQ2lv#Y%+*C8RU$=p zlI$X~9yw51WrzZ%9^pw$d)Qw%04Zu55nWh3dS<4KRp}80GnH_XT^K>w zGmjdm!?P`r22Yo3U=b)Yh&1M}|KuPyg`{voT#0lWRy>t0f<#mmnVz^sLd!AKXz#E^ z5<-VCk32O32F09iic&DK0pbz#fEh(e@ZFo>IV~ zkBB>fn|nh>mnCwt3I(c6+`aI8GVSv=- zm3c3zS0+ec3=S(-P202|RgXMmuyDQih*UsY#{_`6Kni78yJp~mJjH_t?d&AKBunMm zZnMGAQXOQ!sHy{Lz{(TY1~Rr!ZizW=jl7wuVSOL*xU{*}a-MqMA;>dHx`#)>tQECR zn8hRP0f1_a=Xtt?^x6g!uvB-nL8c@2lF_OA7<*SsvUsdCP}$R#*5Urxw;ue=<lV5fmUSoYu#R=CKyja7* z;#a?Z8*l&SJ$&aoU&lAT{u+Xp9c|A&FThVh=;j8hu9M_^SCf!+;t`SwjVM<|z$##7 zR8ee7L9I(8>Us*FARn7HuyA6Ah^MvP(2Qbp+aEGQMaen<&?>0AEqJp50xV@NP<4_V zR8ZCT%vuFp3^nwDqCS@>j4x)NyC#C8;}iVFf9F5Iyg7kFFrs>9zi}S|0{A|!0Mh57PEQN09xxaWe)hclc9rYq z>f^@!^DxJsri@zF)5wj%c>C1L2zu>*{ib-#J$<=uufJ}7ev!)K z=EJ_MNDI{M5JlNns5w8@}$2iX)*+ z9`h0otitGUK(O)sBmT1bitOs4dn%_<4v`uG93=a-2!QFBXx6Zye&g!LP)W4Da?6#Q z4y+m(C6JDIF{XP{!2owUS8X;R$g=^dQ9lEK?|4+v^s+a{hBCOul^)&0>i5Y4 z{bJhEK8^vejky{8)YT8NgIJIjvWyJF9bG=rS9JWXw8$w2%Z z$w(=?a%P8Y;Er|0a9qU*xGkj>DYr$y+`HV#aKl;3*x3%!W0(M)v`%}oq>Jx1Wl|0$ z&e4c~Bf&E6@{CLxgtl>N`1~c$RqWR=`{vV@qmu+lwL71i2O#hOO@=A@qt?j212jUO z9~65%l)_Oz(Z$aVC-#`7?o7i6NfQbS( zv;j-bX5=4!n4W2eiK2sZ4Gsd(5Z6fr%whKVkLvqW)VaWe?bI50eAMB|)p`Qh&+nMS zf%S?Q>bu*s*6FXNsed-Qu6OA;2#53+_j%K z+oCDwpTc{to70cNFRq)npH{hQD_wux=WT31KV{l(4fE{6beck;fns}U19=HR1@IWY|cUQ;&F4)KI8^Od&hpBo=s7 zDnEP;WhHXfj|8D+AXf&eE2jiF!+wiU0{v=_?m$jb$+Z#(h#DIWrJ~H;c(g`f7_34~ zu@y$Mq8X8?6fIjkj0}$(9x*0OnA%VpsPlI&dOmJU3GWYc(ue4KjX&7@s`y z1tUnA8CrUHr-%VNS1kRo`oMVZe@5L1*9QwQ0p-RCHYQ;5!%012>}EpI33@JABvLLP zO~A_qn+-5)#e??+@4bHk7{D{(#+PQ?eS3=s4}r~mg4bU=#;@Og08_)sD<_~rC^Li0 z5iUQtTpPm4$s9h~+&sc`;?$4ry)Ej6AGVVLCub8*Z_aMa7RFo{^UOGZu;A{8ThNiG zZJQ@o%DDKvn}~4}CoX=>59UOj)Cp$L>5(h?4=*tlUwaxnQhEQUY(_p@aggQ|~p|Bv!RVa4iQL$7EQl+IuBxcN$ALs_( zt0|l=(_A@igcrDRmd3J2S@URV6zx{=16wCiXj?MX9Nbe86p%+cOV1@!C*lnTf~k0< z8W2ncMlMYl9wHv`yKxvI<{m6u3Rs*>SJ1q32~nnJlMk@BCkzSqOmnYQ zpL=0=Q^+fdXlFS`Dal5L7fxmr6x=x3;IIGkHJo28c;}sa_}MRaF#HC8_rniydbGjr z5~x*i`@ub&ofe#(OgKB);FT9{;)6R6@$w5ZmUG3#k%}$|7i#eR1UZSuvQ~uEd>nZ& z#H$LN04OfsncS4 z1>)~a_vm0M1+mbhSyfd?wIEO=sGNIX5T*iHk|aWy6BFI`Ge8Vt1#@@=I=PNpUobMJ zDgaeX>`{t9>S>|j#1nzHIYZJL#X3$*p^?rqt*{eoiW;ayJ!9`lhrSXiY)L~eDXA;? zx-AnmM*=m&P9vIRL?m3QK+J*&>h%|kAtm3(^PLO>QCWGYGHH`h{&$jq7*xfdM3_Q020jTf0Yz%kl;>*FB14)40Tuw8gwFx>2yN>3 zu~{3>Of{qur0ZB4pp=8v_k)oP8_!X2kd4p?Ld3!7Yv4mSj+5lY35+wtWQbM?kLt&k zWX6a@XW@0*JR-wuUbQ{mJ-Jgagv*7P$1QSJkimC#!R5szj*pL=U?;v8Gc%gg4uFgy zEh3>`CXfOU&n}y)^fU<}+q?@kh|M)X8+QF5nCKa`bR;N74|D=h9!TUmMQoa?zLwR~ z8=JaQixYdZ4$*dXJ-vr>I$_2ktUpZvq2;!I;FwdaESgK-?8fm6_^tuwMG?>U!FHZ%({|Da=Ck&sn z^E~56KlwS{d+#>>@DG0#fZ?Y8ZM zQ%lG*jtI%wr#VA`DcaIat6bw0<8pj_jLq@p;DOP)taYuc-(`6c0Ps=II`quPUGuDf zq$hpnqd=~wsmrGUfL&)iJO|*O7vS((ylx$QocZ!3YyMGn_&D#*L!vM8oZkb-p1K^8 z1D_-*@LAONS=aAr>-0sQFVC{+<+9H%rGV3!IYzx^cW?B;T!XOe+C_ zg(k5>hiB)1Tys7cmFrNQR=)>!WntGMweX>hE&bnk|K7{?hFjUXAAGwc^~up)5i2`s zT~TZ8+b`{SyV*{A<-lh>5kc6Ort3_``>N^ci}mx;afU4%6I+D(?o_;A-?7du;#ooz zM$NCtb?^N;JfaM3-A^q>BTH>Xmb_X)%Oj(FT<}Md{E@woV+9K%c*q{9SL5uCG>Cvh>gq8PE~QYm$gBf% z85)5C5N9uKei0hhP`Sn)J!9I2RK2y&l-je&`KbSA!s}j%KT?nSCC`Sxgny&rGQkRHyV+Jg)1eyRed&DK$3a}H{RKUj*XfrvP z(#*X)3Sqf4EL#S@#E_i=L1NnpaCF4jFyWiuIKp<3m{*ML-EHgclP?|P^wm?C87|(x zgo@($*0D#pQ($}N60#F44;S#v*qqHcd-)g-Ke)iOnL%XOKHPakCIil1n6bGvLBud0 z6}9a%p(^r43Agvl}z++}+{_|L!)9UN}PG0{h?` zo0m>NxQ&46`RiJDNXeux@?CxLS#>+=wjwpWYX&>)=xW(pd ziUUrAMXF0B8Yp1kh8P`QtrmO&_N)5CRBba`J%IAWNx2 z;@PmZkveWSVi8eoh@Wq97!D#(kO#>;1+?pVjG_gsE~8422qXwe!Bj+s@lTJW93&e4 zJ!l$u z)s%wN!NB74(FtA_1i6@NNroRb3jv1ubV3kd(ca--?j5oI4br0mCWI3*0p>exjp&jT z07#7pbsXt~mE7ZzP>_hFu}9HMlAX7h`oFMVi|_OveT>W_LwSs2H$zlFq>&F=n=Db& zVU78lf7Up{Jv9lnHWcmSB#crv- zw=g$(sj01qqD8_D5O$Z5S|#RAkWVOdJ#Gj?Hf;bLNnymHuX<_{%J1`fn^8b5M_d ztO#H_1yuTvqI-!C&CqzCW;!7Sh$9(uxVLH}$OYjD4xTr8l93DzErmx7!kvb^bP!B? zdqWOoG)D?|7$;8l=bDI<{3ztHc9Jg;ayt-UgEcv>8c{%_&&6{8vj#|Ot4o4+9^IQs zz(t@YPH+~2>E!(`2?7SW)m;BEz`Z_FkP}CGVmPsC*lTkL)C{ERj!ogs%HjCY4Aueg z?m#{|z!?BpMzHe_ypAd^BdHYZmZi0I**US%$E0GKTo)GtObwf(*<}H_T$?BN`jx7f zH#1JpPO)2d`1W_chVOj)Yxwmq-@=_cZ(2WaBh>T&F1qx zR6v1!GKc&$3m&e^9U_A2jLU})@%E2@hOhqNx53lK<&y%io&R!l3=>6N7RYXaf!loY zJ)}o`ZSpg0)093bTP$?xX_`>QWd*Nf=_q&ebKd)WBn8mkbx%?rrPc0Va~;6)Bp~A_ zS)QZ~*Okw*-oP5&__)sj9^IZ#g3R;0JiGFw^WbsUJ&QSg-8+Uo_#>5WyMHmtDBGUZ zTHP-rUhpi}=d-Hsvy>a3R3H8>l_cHl>k6OsUiRsi#2_1?f)C6sTm2a5Mteu7Bk*W> z-8v%OBkO`8paIYV93=Lc2mY;4uhjraT!jz!4-}ZM?DqX0YXKC-Dv!h>3vlFMWH{TS zp;%%TW8WMglm#YhyyFxWXJEYzhfDaWHhbPp5^AI+ zgP$Rcj&|$&uaR@A&~O+>Mt=(2+a0m5pC65D5OoQ#y<^5Bt{MOHX1hI3%q{(+2OBS0 zDFAt1IN%r#htM=ca8J5n4;#mU#gHXEkXCL=I)F240?0N0aE<;5B zJi{1Aph0gn=4U=CuslxzoquHC#4-PyBlj5Qf9Uk%7W<+R>+Iy^gn)VfYwoHf(-x3)tEL*pUC z?fyvjsz=1+BZfjdMscRfg$W;2A&9S{cb|V6l>nU9=)|E$@^N69a zJV$fvM+uF{M^XRga2n_97L$(SdxeJV_NatK(N3*7qSGk=ut$&`iyI{5Rl zUnafC4IWsU0@;5y3-SQ*t15gQXO_@m&5nebwoFsuw!wSCuU;ubZhLqtO(l;QqvpbL zB0rGZ)dln9Bo6Gz58fF)lr{iNv2mti#DGMkE`syqq@sIFRkSrK`8#=CQeVtRt0{I0 z9P`wa3Im|5P?aEvl(yNWx#$O;v7v@Hkq%K}WYJ)?`+;XE0COIGI@xQQ3Dbu2jM)!j zcZy{fTeBDn5jMx3HtSL%LPZdOK;jX@l1!)`J4|b9oGT^q=d$&v6TCB&2?sXFtEKKJ zzxanoy~wUZli(; zkcT_q#xdxHBgjO6OsEeoz-JrC-7U(E4K|w@7k4kP+X;5>-N%hrZs7Q2gRL2so#6PT z6HG@Q6=r$3#lyQhT%LPhOQc-fPQbL8aQdY)a3R$59qzpQ07oY?ZhZL#)NRH2?Q={= zlaDpklTp3b__W_oQcE}6^rr9G09UT`3(h8wg zL9K>GsuQYqg6*QYoFNq9*@ zV1N+~J7Isnh@#fo=AV;=44K+lmKvlPYX-YoC&Y+)6u_zk35!UBMC2qN34$R41agnA z;1@z6P-r7BT0$X)APrLY=G5%>w7I&npqUalt=>|Ag&RRolDuU-du{@j%}8#9N{hLw zo%F{DB2O6dQO7on3YY)_0Z6f13g#&i6coY~A@;Rc+LTxXsOp}Inbw!dTGaXmPFk)N z&fWr35HaAoNimO}WZKmxk7}8z->G}G5@8~SMP0;d3=W}+Vp%G-i{P}z{;nG2D)f2V zmYxCC>4hnSQ!mH}pA8J}Q_O9>Mga8srKj&i;W)LQUAYq35F@+IfSt@pmcvQwkT4ZWw3LVH=q${6^F?Vuu zG@CV}B1^lH$lH{E_cn+-6RNh96aMX54&*#_Vy!l!84!T0^|S&ev7cyagh3cIL_aAs zi0MXt$RJfBft4XZ2cc{ zBkMF0KwaJdRR~-K^CZxTp~5Xfov)cl1MYWpFw~@xt~^Dm4p9QGj$6t|HBU3k#GZC& z|LS%+&<*kQ?#u{xy%{;*Tn^VNa6(?Bjuv?2*$Dt~TW5tB5JfEjEd(wu!-zPDm~J!d zmMzXNE+C?q%8Yqapdf4)!P45pzORT!_uJM5Toq-S03uY%cM|5AQLABFU5`9IIlHm6D6vi+ z+`f%>e#Ut1yT1pBdBhbJz>2RU^QeCkj%uRf9^@^`NOx^xaOe^KekY*%Iu-S_#mwQ* z5W3d77ijPI>%f|k2>2{ZD&&s?EU(vZKRJNu5i;1HK`YaAuz9{AM(l>|njgPXw ze6;ouq1h{WUf}A!g~KPcvzCK1&)~Sx0Ww&o2t7ppGrM}dJC;T&(}6@`iWZ1q^`t|L znFE#FkHV(|Ns0SK{rmR#w8qo=jQ1sp>X3{j0%?v$IMSMRqEcfNV6R_RG^B$O6Rov> z{PKEz)v|?Y=fx+<16%EKfr|rZ?3k7aahQ&z46p-g*OL7XmAIAzH|dx+0+Wr}WYdP} zJiudqT>$8Yz>C3cjPf=O8%I=8+Wi!D$g%KeHq9>V{|F{n5D zakJVVdxX~H4jPhlrtR}pVeCy;i~7ddWs9iT0FlE&#{d%z=kjQKtkqb8!?pcc2cvOf zk0*q{PX_$OU%A%%42X!Q-f58-Ae`hdU@9pyJP81i2l$9edsO{60O|FP`)K_qG=kK? z{CB{~s*cQh|5nZz;(%9X4zXb^7=^r#=Q&Ogb>+-PuWmt(s~w$Mih_etd0|Di#|9KZ=1{~ z3K-mwd;kP#a>e({!vzH(5^^%>_}olb4+_xb5=XWm39P*ZH6RR&nPFg*kRfB5dw&my zOg1p*!lI~t?2i$$Fz+HG&lWMXfw@GmBfpY}aP#a83d8q~zm8?8U}F6IS8wCNgNx?S zn|mF_^cPbQd4$ZIdwtHQ5QO7KIX74G!?(l71^l~Gny84uvD~-z&Q&sZGjgub{_9t= zHVa+3@^HD5K0FHVvxPr$8D!$1BsN*r#BZO>lpE4v#`7~QLxm20cU{Q^{k(kq@=@)q zM~%-%dCtedXdZXnv#RS@y1ae#d#~%?$JOi8v41BUvJzR6-VT*RpKtd*KXA=Ru3ksc z@^H00+^fU&?D^7Knnf{BAxV>YXm0~{i+Fh5WE1Qka;{$PKUKOQ^bLBby9__`yVUa| z%1U1Amt~}rR6tW9qlkzQ%KOkUGAMml97h1`E)3YlK4hMyIQJ(c6F;Iqq=Bb#m?}$e zgA*qs+6f`F+h&_N>1LRNMra2-S8Ub=&;`(9kjkjc#{fDjPFA_IpuDgFPe82&AHIJJi@XhH;Kdh@LZ|B+*zt=;?yXRq0A(;g zSPUcN{DVu>onmuqgXxrU^wNP z124%PdB_EM_zOrb_-o&SYm$fOk+<*E6VN~bRarU3;O=IsB3y`ws+xtzkXe~Eph|(P zh;X+-2T@T`(N8{6v2>WbHwSQHoIg9kbUkDDdIHmg)5k+S9OE&eY#8Z$KsrsJ1e6)L zV8X@ajN#{7><7a2>lwQQODTOiS{t{?nX`cO^b|BOHbcVx`-foQ15rpDQ9z-z@8c-^XnXBtPb~|8TV-F+% zvj}!M*GXjJXti zIUn$Jvq4e8wFv$&UE}8`XHaQCRx^!#W8ifw$quhAYDWE_m64b$&?yXGak>;$GgfW0 z?on>)vIDL4BPL^1E1hHP7QN2C9b0A$j3>Ho(dGnEwT%P`;mvN37yBLl;rT1<4ijD< zCj92r8~ojuU*YGE9%DacoQxa%+rRu7e)Y3w#+0T9?@QZ!5V?ZWZr&u7-{)4!(_TpnVrYVbNuZ0Ek$dOV#xreH``ajFhNe z#p!4RIGOCJ%b`@MG&vW9M~=uHbkf-UL_Lx{YhC9T=~2aGC>RP$X=xY&YM`EvTO?8k zqmFy@uaecbhyf;2fvv+#&>Z)PZ`e$BnbZIZky2b0`-3sgRk>0$U{}0P1aP2IY?e%g z7)viXXbE)Z5sm9>I4nhX^?I0~BA0?ZX9u&gvo69>j=`KJfhP3x0EMCdxC^>) zMyalzw%<2nzyPXs_{^ptLLu_3(E`aPKOz997Cky}!kDN9-?VURrQPLH>sMJ77vF-x^TYyg3z-C`do0De7J78HF z;L+&GP?X(V7L;6&MUZkq9>h}CM>7-RU)NGTzc0kcIqW@h$1L_r6@b8SchXhP+7D8+r`aw7-|fXjr*0D0)b#6<8ScW-~Iu={Nc{EHX(FaP-;u|Ei2zCNJL-Z!)dQNp9MQ(WyPOj&StwlOw9 z5cY=|Ot}L6itqVGW^7M4N4CVh@^NQBvav=QwTJ-_#cht9oiUOtL$ZdRv4zxtt}v^m ziVkcH8rap=+>#O)ipv+T@Z~@K3qJd+zXXlOh|VGwJ;W}X#iHo7RCsUIGuj-F!xs?ELpar3|3zqxq_3zz>i;Z%yA~|}cQtwFkM!ar| zlXybx67Mb|iyn<2Q)@#5;PiMIBDf81^;y3~qYeEW3qXq2UU2`1)~0GX&dRfX{;_lW zhe|{BZPw@N;$Ph~+*@(kZgJW$$m<6qx1qT1Nh1SnCDPW>)g8RvkD=QN*upH`W= z|HiLO z>$Mvyu78T7kQOyr!R+X^#`t$4%a_OHx2l^vbOp6`i{(9C)YoK?yU!ZvEc}PufuXuL zFMfo-P=N}<71+kR5+n5QU73`v&>?~a5U66*xh}g& z?HL{jRgT-&o+=i;{=vpvBMrD%1&S2x_mlTS_+9O6he=u%CyneZ0!`G$buoWjFLXX= zS*)E_uaMR1BlT}6?sY~(1KHWF)U8#K^#o8zC)XTv+w)&9h>|Ei_kMB~Kjz2~#@*+r zHHtN)hxrr2w+mF3MDObgHb!LM2sEPkvHJj8vrl5qQO$<6-EMJmvIRu&*Z=0{=F?3H z|N7f6@cQ+ooz46D;dDq9V%N(wf*ls*fI+eBgi5GcQPkDUUFO=oWvT1xM}#^Dsgu#Z zgw!rq?c>*4eV6O(drJenu+_Sq$Sqr_TUD(B?Zg?V0K13bvy~$;|s1P+&M2kT%H<`(TWL`?=ui)gF&NIWvP<6t7=RIDIlypi}rT!tgRy z8-PiXOGY|L;B7(z;rV_Kfg&ke8ZZF+BG7?xda}ivS3CUi;sPI^pW^4+b7QBBC>m8v z2h$S!EO;^P0aXONVs^HlgA|O3uuTI*1=l&_pDr$ti14$sGYsGgN@4Ys*vbH!J^|YX zoDl?L25uRMAVeq#EP~bur6TGKD9yZ9G8RA*a-iJpZZMk#V)eP>Dg!A<1#Xc>#1`=P zU%teg1aGbncyW1+XWK0#7yLi|@wfQ((`WeU$te`T>#HlA|M#(NSe#ayJrb)6eyZ{S zGC(9q5v)2XIe1RZaW~BcM2gKg;O8Gb!Dbjd;?2;L-QEYPimZxB1#>ANB?IO%JA zOp$rtsv;LlCkzpkDf@UvNL~Q@$kR0ze_lYR7|jH8pb@%P#5ylsibmDyY(iY?%uWnj z=LVoMC_ycyG{KX+ib9av3tTB%Ms?e4H)vPPYlbmcHdZ-pjWj<#R>2V3*>@_D8duD5w{Q}A z-$_C6UK=3Jz9X2Eu&9EH=`~}2v^WYIOg3P)i^IZ%)ds{@5%)#8azHcP2wEBZK<0>Q zOcQnw6JQ5F?b$_wUAF({AZoF7sl+@B5TH9!43rsxDGm~p3?A56>k2UB8IqE}$90sd zry+IFooIDl!qfgdhF+2Oy>u+4;?Ba*ZLXhk&PX|7PR4>)=Hij6TF<`J!Oe!3 zQV={X#CzBWn)q2-dT zUTp2jSs;>;CHn!F+0qb#lwfvqSQl|k^;*ho@*%dK6fxF01~ABI{zzu9I~{|KQ5?WL z=NTD{RM|BWPPSuZ?X#uIWRz3qxJ+&nzyNJh3YZ25lAA2ZEZ7VKPEJlhOgPn;zkS9-D?)qXJ7`XuRY=J@N zryKn0SAS+8#WWgdaWi5}glR7LPk;Xp*zYogvdp%BH$?}oIwj1yMuC5XHm50{- zM_uvVE+66$@V*kV)60eJOU>8sdv)KxS05#Am$=G2p^}mt)-&{t5$H4NZUhoeNFK^pM&vjf;(-GOgi?n13?6kx(}1PfZSUqtGSS@^0{vu zv?B^p(1J{0J(gNKqyd)z(oQJXa@-mQIimL%3*xusZ53UzYLvEqZ~i7UB7h^s0F!s< z3L(#@=CT6751gDyPQCve;2Y-_@&4|;K?tzWw60!?L^dV>{O7#^KwndLr3M}Qym7Y-llzmkJ~7l;J=-8hmRXZsMmrxSkpbLT8`vxAY@*g=xPfrp zhY$02*&XI*)&!sf7aJ(cS^1bMz^$?9H7!a|2Le-Vi(Swh1gc^|;eeg9P|Q%job6fc zPB;aDiqvWwxK9@x3?;k&PsKAP2sTi}fr26cdrM)c{!S4mCTP2R^)sy)hYApb1Ja$a z#6-jU!u1FP5LN_vhBd}A>R1z9-#No;y_H*kMta|IV5Gzjz^iDr+V*;f9b}@CY-mVu zoJ*3giSA<;Lh?1h6HVJs1w?}#GW^6ra%68%uXj5MQJkD^Ez1cL{^BowhH09S2FCAx z_a(mi>P=-kRrR^z^5H7n&p+BcQ0abG*tx8VWg_x5OpmO4eWCRl7(yni4^0^D%+5#o zxcUl~*xQs_w@Ag`E=Tv5JNCKO*qiU_&AA6{rF3C~#kqH!`2yajYCcA1fLT5w=4E|M zFhzH5TmT50P1e4=Wj#Aq-^DY&FMFx=0{Gwox}*H5fdB66hi`I>m!R*P|`@1jFT_G?QnB=GBcGyoVUO;SI$fZ0|WAqEX^6)_yrJy7#48=#xNQvF;Xn60K7>^n}mFr zG3^9-a(2oAI6E!4xXhRj1)6}Xq+ns3YQmc@b~w8b11#+`&OyjqLVi909|M6_DA`hu z5de&g$3Hs*K*%|R6Qg(a^<`J%=-zNfbpX(Qew<=LCFz|Lb%QuFAqBh>?!ueSb|Pd!qe>* z&ks8=6S4^YaD9#9G?q++Ln)q4!FF+9%zMmY2CIrR=S5$XE$XC8c~%i6F1CpoObM1i z*q8vrNe3}d8-dURLl7I(Ta44=5JB7Ex*MU%w{K7x78U#Iiyi2kEV8C39&a`{A4dFc zzCwXwGbZFBczwCUtBdOv$rcfX+&1V2im{DV8rT5`j6{TCAOp!cyCGmsn|V@?c$( zZrF!XahM7QXHklcb5S+c8@7$@Tnxx6*)|q=F3wJ9z#B{1YQRGA@vuYi7I9|27-{b* zF4v682v>^WFwNNQCf9kknF_!&L{Ox7{T#$o+F|>Yr#7d_jBW)yKW3!AgxAGDKe?=; zo@2AGmY%ibRqDd<6z_oKG@94ibQ& zwxO)@MDDQbt6CRqG(QOre*p>mobA~;NwJ1*Jh zt}X&!14Ni3Z3KKNcU`JNR=>(TX7!U`FYAF$UiAtla@k}!xJgO{GHRg8VjYbQtX*t+ zL!z$zSjT&OOsdfN_&H#c$Ntpf0Sxn30WybXYNCy@cH)B(EEj!=3%0gd%j5sY@K0A>Su?)MX}E_XP6^4Nyi zWkR5qj-sFgx`{D01`8k5on5)vU@3X)O4T9k0BmwbxR7hZYzC8G0~2YH268SAWK~#y zJLuQ+L(FHXOaiU1y7?opbnm^R#KSsGPkF?y+>F_czOIK24z!MCmxv(L>RP7?7%;qOsZNn7B^;43O?T6;<3R$jwWw74z(HmVFeOjL&0uHG4#wf$ z*HJ`)JT)6E)Br8h0jaMSSqdNqj?dZFFVYMi5+cnnF#(w{&|vdj&9XCqqqVJ+#waHc zO!JI98Ay$i+l=Zq4*@wBOp^g;+0%>NiT4PNVb-=#^>6v|hq5;yC zrZ;@fkpe=DLJs^_pk!G8PTAb}oWPVZheKKfufO~fr6_*!cYk9CZ^h?|6jYW;-zRC< zuqMVnRp+WKs~y$PKZON%h&m(Y+RkmZ!~NykIGBH%av!+myIgJ?gYTkqweRP*k%_y2 zfNvv*Z*%R3Dt#T+j^!U>`8LL*f9IcS|98g6dn@aC_-)Up_ocJfhgv_DKh5$X*7$yo zRfmlMveW{Xk~s(J)f(uBl}#lb0LQlDzNcSY<^j?0eN*fgSGB2oG_<{{ebG5AARrG0 zQR_viYa+g}r2E(G{sQTodJnSx@uN*dEq??Y*&`or$1rTSUH zq9p6@{>=Lr2(LS%uls0vpvq9cUlkB0B#Ab{-58z!?8r0Ajrv4ewbo6lI(GZN05!L6 zlmPj7$M#3@8Y80ad-rS=H3%>=cEQKfeT2b)AM8$bAM6jS{&=7rvvuvMKu$IJS&r*U zH+x4)?Cw{fkm{!B&hsqg=IzWY@I4q*9Mp0IC~?cZ1gj50Zd_ulUJm$*?J2v9r1a0% z<YFg4jQ07;Q>l`2!?d-HnwYuH!!Ye>%f9#XpXJ2|X6S6Oj{)X9~ zA9(EU`e2c>diwX?w?)mrnz%S{&N{&SVG1F25McO4&F@$lWf!t<0l78e-jP{kD^J(^ z(KFm!p_XRO1GC$;R2`{szdyS5q4fuOW{BXlB)_>{Noe|(niLRxBA62l4e;&fTH@~` zm~1f`5D~GMGzC`c3%lN9{@c9sUn(Bmkd3I!f4&~KM^asf8e3kxy<-TBHZj+_pi5!R zT}P1jSxwFEepX`&hU-6n1mFO_8v0-Lf>oW-x;2PP3QWscx?zPviIKDc9svtBZS`KC zVESD0Gr>{_C)+K~PPR}|{OT7!#m|5CDSrR?bA0jqrJWIkZ224@j`JqBQJAXSM*T}c zN3?Xj+{Su)^TI{-A6#w){?%u-xdg!RnzrW2TSpAoGZ?b8ttg%g$3W}D+t8hFBj#>Q zBXpqJYEK>MYrn4%E-dx$@{eQvrMNi&Z!rkpi*nrd`fioJ-+PPshf;dkzOU`yuCI5^ z^mnUWdP`9#hI_9{uy)>+9{3w7p?ajV=ICv~a37#jM1(z&bAGQ!>L&MS;q`^T+Pz;;F4qp|OjZJgGut|_ykX7(^=@I^n zPjLA7F+SoEI84}xAfJqQGY+_ZM3}BJPF`g^KHcK~ET7`@a=`!R>J%GNW_o*mf{WKXPe?h}iK1SO$=Ykkps~l?hrxMl3RGOv%76Nerk71{VVy zM1;$-Xv9n0kYDmmO>C+Z4%l!bZ7u@J0@^Y#5dQJ2*ZA$rOI($VO|tY5Maedx%zmh? zbrTf&r>LOJ8RIZuJ8S?5h9T9>4JY=fBdZ57K#nDmIX6&Yn<`*xj6sPAfB(DB@%nOy zEstQb6wCoa$#r{Y2B)#hwLT#j>(AjjV>%QZvat;HfU$8*7?=Pds4!Fu%4E??%&@gW zf!$%kIHIOTRNp{l&vhE?b~$IvSsH7U3g(gxfCp1qBLPEl_C`1IBi*W~V9o~I3ZRw7 zbz;D$X)d_l&A8eh`u(*zPYC`z0PaA8piAv1I84RZ>a>liZQ8pHsI&DLP*Pj!$>?vN z1TqUs&dyxcN3S`vp6#|On8x_5f`QMSht7UxEOicobB9DqfFV2K=?V-Cm}B!yNTr0KMaOG093%{cG&^twsx`{AKt1K6>pe%(Omo3B73`;s!!)Ca z;4o!G+EPHBIf@Oq>b;j8s2WO<05B(;a~ckOtpGl=1>E@ybJAGdot-O2MD5v17Li#3 z5bIa4bYS`z&q#rQkO#LzLa&too@tYr0P}e#hl7ZdId)XY*mM1QC50lGri_Ku=8z|( z4yPOg0~ke(g-gZ2x{`dJc>2;(1j^?4wFp>tIUxs4a-E}%xy{%HlpBL$^nH!YtN=fB zj>_mgTchentD^nqVQxl7-4u>a0|`mJm@7CZbf);cv$V8mtd-KS;Ay0owZ5ohnhO$J zdexE*Xk3aKd!_H$n=NCE)1?&ToYB%gVc{gF&O51a_F<0zjkP9Zpj4(ls-VMgjH-w+ zrWJ!?MMtSK5QN_90fZ8HqC*%=9oK&AL{qyQ3Bozc=yz_w{)Oo62!Wk!(<@Bq#NP03_~ zx#~qx1(n%A_oPr#M5>q~1#>n4I1}SAW$dRJhg>ja!R(-E5(TS5IY9-Oa>nTO485gl zfPZFSb24B^$>&uuuq)i|B60mGU=~byMlO~PxB+297B#%SM~et*lsd$0{-VVWW+j~T z4zTp`7ldB%6w}JCYix{5DJXNnl#QjW~j|sw352lxMbnS4ut;hqf`?kyX83Y*RyWGD~z7804 zJx0fz&2J-X-?XE2-S+Rpy!bwqw>=3urq{lSa%@3q_TATe?y=wBcloXWx?}#|rnm0` z9RCmxN&eK!x3zw+=5shz>Sj+7tl$D?Tz4PQvgqQ!5qzgTxW=Mb+wXP1)K#UP;hN7< zN@Q(V`uhAWfJUHG=QGzeplLmicnL~E_(hJD1`b&tC2N0|b{F+c25P!odvh|Ic=fWz z{oQ@F>f>Xef_g3$M-Inay#OLR3B1qDuK_^I-I^qvs-dqGP-hLdrx}1l6u1FSM7w5L zO5IOXUty~#w78h`K1KHl!u@YOVY> zJafZxO#AuL!aN0V@K5VJrRG=YgDII9l+rC~ynBB5Mc5tSGKq#N9;hjj7}0 z{PFJN80uNhx=1k0^(aNA>KLx9dVP(x`HjP&#}u$ebzR_%asR$jJ5Qj)%y3 zDxkVLM%Pxo;+;}-755iTY#*%VCvcTneedQ6G9B#T*b+J;d~3$eZ$3wp^L7+qJ_Dlg z?^)Z5JJM3(g-p~Gw=kcN`JK!!6@J2|84E-iT7U!#B$dvOd_zUL-$z{+fT_mg`fyp- zR^VT!f&I%04)zx;ya$Pm1S3G$m0{4%y;5Rl(2KP$>Z!G_DgFj5lNYGF+~;54J{Lg_ z)Fw=~`|)9i2e9_L=fwP3(yG#VK)tPfFg#V@d!S2831FNB-q;{FnT z>ZsA(7pt!uo}r38sG;1WcyB4f3}#twN2>A$$`@4kFj z_Jbd?to!C&$LX8ss~@6YX<_x>QSRF#-eQ}5$I9IRz+NFX@OmrXLL1kwiz)PNb+yI@ z+so`4lRI8{MLV2~Lw{p=qNBv8KZv5;PsMV#wqamIr7Q*-+LaOkI{+BKTyS>EN21zV z86J(5U3T7Q%onr0Zo{C_X@q0fFi@r6X0K8mTV-SL>TE|QTfb!zY?OeL0nCaGoI!3N zTu&Lhtztd^j|VqI4}z2!v@+bhzX@k|9jIXlPsG~(l7#D*DP91i%OFJA*97&ij|PZ_~l zcRVU$EHbQ^=Kc_FIgC+)y=s~XPd_`uW;;TeaVUa$66nC#oNbIvPK~WmvLE6Oglh=S z$rz)4C)XC?l-S2fs-sC%QL>?ba|K;BT_D8(Rz(EY68W!D0T4_;?&ogjY)}zHD|LIl zNRP<#fBj>ErFvd*!leAQVO-g=TmP zc7n`m?H#nvjlMs>xPF7I1)slugDDqmwu3o>9Qx9A?2Z z7f&nK90`&O3b!=ABF5w=GwdMTH)gqrrT(r!5KklOfV4ykWouJ%02KMysVE9(BoI97^SP-KjW;S5nECz-2la$t~j&RP*q9iXUys!|MSXdo`B z{a#adIFpt!Dx&HzjZiBetegw-?5RmbK*ZJmEb3rO2~b{Rud{$&2PYNNPv(RGfmMlwAkA4!7B#@6Kz2t? z_OzC^i4_B^h^5HRK4x}*Mwtx=nv#Jfdqyb@4;%=pjKmG-4sRnORYLD*5Cbe~uqV2| zCmdfKpjrapYn!bW?hWwN3!DT4Q3WVBCOS_kECE_E`zOy*0b?XuBX>(3?{LKjh*FwU zQA5VV5O=vyMFqaHivsloz$EJI zoe^nwA{YozbBH+8MD3Twp%}TWxF9%#9ap`~-gow&{=6#Yi184+K2^6H;~FAk@EuaC zyAOzl2!mk9N& zVD&X&o@X3(2b5eaAV(A!fN>bB9hZnO5Gr6c(z1{P`^o1xH2iSX{R5zpQhabnud$K~ zq_!=I)EQb`2Lse}K+HMU52!y;>j;<8BxEegxzcK{{?Y39@AIyBIYaNh=DzDbWI5(J z`9AmiH&Kr5(!S}^JLYKh*^lMhE#I_k9GkMz9+;zIAcYL?L=C;q@W*+`HHb0iT zi&;P(T&YrRXoSD6UTOQ?<-N^2(ZEx{LWUK7A6ZcR5t&@>vm9aN~LgsGGi^ zKtmm$V)e1~8!%ctgW|#nwhaG6Z}gSBy_S3S)ujz1?se5RGs!_R9CN15$?DZ~;91P5 z*?NruvT6aX@8BUZPc=yD^PP>VMSzu=ec> zZKwC*VZy)DSUQ(KZ!}T+aiXdxtg1djwO!%64X;Yb7%G-*krhO%*KyV1_AViI|B3k? z3#eo1k$TQ(sznf|1F9zLO*&d%Mv!8k;yG4@niM8tv(fwyijenS7*_l2HL$a~EfxwC zF`)Kw`1n!%OZJ_ExE7P7t5nEC{jZPU0%Yj=G{9taZY?KiJI`pkf)y>$9e(ECE4G+K z3w5@fdzJ03%3ABA_?}<{Dd^g}I#R5UuJs4t(a|WP&i?3q8vbhXK=@uicEH1!2NpaW zr~)*wsOuWbY-0DMkbgfH5ty98!F9Is65yG6dY`t9hMkiE;U*8JK=ZpLCO;I1ktD$6 zQrrg&(wbU27lr16?RLb;b_0T7Gj8zdrypY&6P`bRiQoV3OUqOO>kC@wa{}r)Z1Qt} zc0TmhCDyJGzp6B~&J|rfR~J8zzq3lyV%qh=>PPOotNK-``h_=wYPY^o7&&3JL;kDy|;tE2jv(b>ut+@f0+VfA$I}5N3#RMY>;l&-nib_x+-O%6w#c9BR}fo6N&K*nLCkZK(FCH7yoY4B|V0Yd^dJfMJ}EKV^` zI2i|Xm^oPE)jZ+xX27RUKgK+ah`=awI1~)S7N;ktDANw*`T}V%;3L;qJlmA80ANp- z=WUxOlL--lFdEpXvl|G&)jVN8PdGo@V6#ogrQnb~npohQjnZva71b%Dmgf4PK)x)v z+(|vukBvJgV6#!=3>;=)AOo=$0XzdRX0IC&RdyaIJTeS6CZmBQq-0obO^c`-+@WeJ zh@eOq$kIU1Ib$x9gAVPQ3}f#p4onack6cqECNTM2$Oe`hi7-;6ktYB=;1TZXZX2&pWG9-2GSSNVE zf_n+-|5$4vnK1x*)Su(cR0@O=hC-0!dTme$Tj~HNKpp%UsVu`ST$w1fSerp8AS89L zkFy>E;T@Pt@hXxy|MS7+L6r$iRg!*_v&FR9LFeLQ^4mO{_ zos+Dh7)@?^FnD#YsHcJ;w~xG1Kvp>M|Oa^GJ#)TPWMFlxo zz2>=qcml{$%>!^oQDYWn_H{|&jGDo$Xm)t*w-V9O#naeo)kU^et4Do1BLRSs2tui{ zsHrAc-f}kPIO1x{GXpdNR0PEttI2h%gmQG}a=*8%bXt8r6Q$N^>;1>)8T+=GS=oee6ki;paTa09RPvBJU~@I zWX!|{R5g8@{4gn49!x_!KwOQvRtPA{&Nje^)F|S6F;QcM6%|mjAe7zpHA*fxf0WGj zW@9dnw8lj6w9VWCEQqQt9r|?Pgy=lP1jbkY_}{R9^BMpn&wG#Jw$(kQgp?8_i!mf> z=m-PJODVqQCI$a>nyx(+N@A5Wu%Ie;0 z`|G~X<+ipSYx{@v)I3xs>^SC|anSw{%e#*8yWZE2;d=gk-RJ#StQ_m(b$N(heA{>Z zSiV0c_D0_Y24D9t1hym`Drz542YgzKW+eL)gsB-D4^+{NJsF^$73BuTty>ixbR)j^ zQ$^5#Reu7)PFFl^u60-Rxm`guR<94@BPbSNF0|3IXM{Z&KEB#`cXh1hq`ACMDtvMA zu%q={vZozCZd(G8y7#ZI>E2O?@|I^tVE`yCEHVh0!vE|$IJ3V4Ky>4QOQ4ce#8qS) z;>GZVACtYq+TI-<@TWc3{BX|G#Z>nI1ghY~`c9VWyK2c$msMVFpWA*lQbN}NMYVpB zV*N|7;CaM8?+9Qs>SY0+H$`M|#!mfhNA!F55rb+!6;VWDQ%N2QTN-T5fJ1c?4yy9r zS$BO3PilUeKFh;mm~W9^+vU;vYM=L7`??Y>bajmWjf+g?I&dgr?!$uRD_F_vt!RKS zUDv?xbRXTZ!UPX$?fsWHE6h^RUr_&1BKHB^to(YAT?~Q}qFY3weYjA&254v-&6l&U9e^c>{FU&2qY+zT# z^&$ziI#eb-FB~vu_KY>~KvQi4yeR$54hK~D@#Fn;L#N(gS?$i%>fcRydO)c6tJ)ki zM$`z5H9ufuQH6sdsmW9Loz-1p|#?5*3gw6fAre1WQ%bHxMVnrvohJwhdW9QT8BL@|gKzHVRvx zB^s;(CAb>Nu0CIF|WTReJnZohB0_~_{qq+!78*KhFoAD){p)OBD4 z-I{-lq2fNlg?_wSH!S2!b%||h3Z|zO#qkxo1I_m$OEwsbkJj%!TCrsn79|$`4pZ_$ zOH2=;s63X9eB09NlJ!deF3*isEAD;hGj#Pc%7>ujy6t&y`<~nM>bsP6zpcyn-M6%E z+q=rvZRMUwg>RwUZwW06fo=f+_Isjg@nC6eohi;1cLmq=SfC?gngyG2)r$nAv%wCxidM>B9vHNNJ#X#|reF`5 z3T6OlAUk|^he@n`Xo-O@wp7L$`%VkkuK4cKX4~-Sd zfR=(;A|0J|q>`ePjQ#Zlh+?-f_BIuO3-Aa74rRt+Kl{NeqYR3@S7a`NSG&E>D<4Zy zOgqJJIsmg7qlul_$&LH~PQXp=;s>WnsGCd?L6&aANan;S2!KQEh_wY0#;zc42zhZQ zM78D7FH`0=z~Zj{I*s7~F<~4N#$f=&z%o<}ft947lK029Ce{1skbU*pNsM^H63 zzcJ?upj31zykqkrTEUZ5SE{A&1Au`I2V6X@@9cdO4Ad%W`wg^A0aj7AwB zLulhf9q^Z2K4Y^g6*N#&q!t@+MH_#KO_Xm&8feAXyJTLb(RCR1=F`=S;kN4RxLi@*yJ^V@WE(m{oy<0$B)5-rgdRxj;^mIWhvEtm-lun=@@X#+_)Rk8-FY@pm>Se{alLL>~E^CIT!K zX|Z|CmiAb+0|Ns#-b5G@JA>ZfIS(ATN9NWw1~!=7*yOG$F5BcIpWnU+iUmrP38p9puEPl8mnL^I!=)o4G9~v6h}sTB0>FZ}r{ffe2*)nEI+(SV`&EJGtM(5fGS}PF z?LQiGX0+2mnbp}6O3!T-RZHK%uG>{n<{9(#b?2Nx1z$&+6;*YBGIdS{wsDZ?>Zq^j zkzgqR8l$Uvnq@88QlhAVX9HNSp=15;3Jz8@z^Bi-kXdw$Z02P1XNiGTi4!{)3AydW1Tm@f|NA?!IqLkVF0+C1;bDvGE{atn-cyz z8LJ%_{=Mn>M9I>~M>K5_)Aya&fNdVdI8-r-)LL+7U)2-ZIdwa$!Pnyk!V;icFH2Ey z@`I2>kW7{JEs6mw#Sd&0niL>*Fku1dXwKyd48>wxp^AYL23|%Z)^$(>5L;u(>qQ>5 zOKOb0;(9;WA(8w#cYLcBi=20`TTL%g4;G>>#)Mo%F))k`)5pseVqZtRpNarT78M;# z5HaONfLt=hA%Vas3QGx}v*{Js8gCk%+hL#Fw>h`V*(qQxU`9J>)e)8+T3X8yGHP)JH z%Ti_0t?h_(*ls&fl@;r&A|4>4%|5a4^d|Q=bGR&R=(j7K0{+%YKk~iBf0smjSIR@{ z_;tqU+bqY%=DzD5dd=5yWUtGgs)P2&a-ybr@Kgz-VCDwyuef4$p@k5`vzUFP_ zdR+hGINvO9+mCmZ?_U2lTO0n*<*n}J=tvjz$JA=TJvX=7tqp7tw%(!~c`Vg?6c7v2 zi@o5|fp`CWT7dgF7$(d%EZx2`o=Zic+_wt#dUI>F_x3h2xeu=2Z`D$&X}hZ1vL9@J z7fkE+l!sacL^nHfF`j^fRJ69?Hhh3Ywh(IVi!{0Jq%t27)O>f02b|9ZaL@LXwi)i~ ztqxdYzqYGf?S+s-kb@J&N7MbnE;F`;UHV;m2BW2hi``5IDRma8_C4J9px!?kTRq#O zhaWY391&?rUR!@y1*EJ8^_Jy0GEOnoq!s8VOwDxR{U>pq7~w}pqKWYHnmZ=snHH~H zLlR>AZ5}qzSYKJG&uxvUuQ<|73!L`96$`&vob}p#w2$oB;Z*9nh=5A0>2oK<-R|>w zf1?J$T6$z=iB?xzDT4kim2aCYca*k|rq;3UOObw3x!90K)&xRr0fltlWCmNaPFA11 z!i6&)u++KsI=_b+aL@dCc7dI;xW6KLE_}A$4!EC%x-4|oS*<^7CLL#;>{EFIt!-^? zyU=<&B0Gj?X*Sf3-0P4;XLm$?4#{l9C`<%%E%LJs(e_DeMYH;#WJJ;W-`^D!9DOt9@ zuKhg-JN~YH>rV}0j+2uO&dyFSZUztmfBf<#Qc7Km+caVdAZy5JyyLiTsPl92wJsY~ zKknuAwi1K3dT7tMxwyK?{(}sOzC@!RVymw0n0G8U?4bueY;E-TeYMeFqe5@<-g~cG z*P{nkzOOp2bm4>VdB|sPTgSCL-(~cC+vT>pJfx0q+b`Xk{h(`a+Fb9iyr+r#fHFMU zZV>4y+ZwCY=;36kE&()@yDQy+fLF4|rOd`^Hvr`lD7z0@=Wnd=2=JDWC%w6mTA;$0 zB@CL|idI&Y_f*k8wW2`XDQRp#?4V5(Bb_FcEOj@N%W9DVusI!!F|Y_Ucg8melz@#N zAc_LHl$zdGvl)Dm`miy008*%?0j&FV0EdI%%dZX?4hkBa_FF8~-2ngT%4?hoM=07}#yIesAi5;I=R89Ffb^A7*t&tKxRUp&UIe*P)uIb+%~ zcr)OSZ?5s1KYW3)cqAGbQ0uy6gPqNS8Ne_Cngx>B*~k<~)?a1T+U|#zG6_m*j9YbV zVa8>3K#3aTS2D2GVV7&SygU?KULG(>#*_sKKuQXRRuECvf;}cbgf}Btp_s1-FBx;2}A~X5_fJTPr*lI8~s@#?QRc0@>Hg7pl1gc5F2w;Vy;FeF?nGcKP>}PORY(}n|lHME)y%_0VlQZj_B*Mvg!e*PCJx-Bl#q22?;cXp915QL**&!Jh z76jNG1P2Aqwj)lrBevtFZ7KxSF`#IBlfL*C(%bAElWZfJivSLM6II9a5|k2%JUuTf zw2ZsR;mJcA&BW@OWT|uhoWi2)zdfWx~O5aJDXU z-~@94RMt!5qucRs#)L`bSmISlmT-X_a;bBqB;%s$X-N6-?Rw zR?8DAF1gJ4WNfob>c)6EvuzvhWBd)1bJ=5!jf&%>ugH!>xzS<<2tPX zJVCe#M04Hr_RbDb6EA`*^o4Pv;=4&hnNbAsjF)1Xg3Z8ioXMJ5hYY9=Zt%1kIxI;EtuhX7_g~=N)ZvNZ5)&eR1-u9rLeJQ&U2OP zni47y&_*cL35+~K!JghZBT{%5vb8$r*=<{~!^)H(xj+YjvPHocDd3`J6FYD?*0-wDE3>Mt zYr*bdi>*h~$5{R?tF7;rOWllr62h)C}kP!a3C+2)HQp3c$RD(t^F zIR9uW6A+fshj*1#-`@E9LzQFoy309qe0?~6-$UPb+k3ysa^Ltw`8Mm=mvwy~TK|VW zZ(Z(d_igpL?Y{3yKmJ%gtn55QH>~gfQ8sRt-iCi)&ilI#0(5oVZFRcq+4rp*Kh$x) zt6#oOpL`ekb174|pA%?fSYBVC-7UUHlpD{`YK~e;z?H*G+xOKQ<$jjRY9H@WR90xv zvKJSx)%HmVTVHhvX!0FOgiTfJmHa<9A6V;Hjr;zanpPE^RjM`9k7t1QLi z7F%1FJ*!aj0p94Tr7$mid;}D+V6X}@^;Z(8`q#n-(ho)5Uw2gk(6J>hOR$s$V5bxF z;Qt~;?^aH`%y&KcIrN-?s;*|dQN)v0=w0{)7%k?HSo=3qz8MgzxM2E z>e(6$b>)^9@!5EErZCix-H(*#z>&cH?^BYHB#H91lrwA-=>v*IFwxkUNutHJ5()30p((rRK_Oo$oKXtAh z&x}Ea8418-&4__cHsG@4@(>_CiYyw*IxHo|n^zb3^7#u-6AWL2J@_=_Em9A6{e0th zJmB-MTRQtD2C!KkRIdp=Na}0jk#!ot?F4__dh?(w3c=eTQefukw(0KctPvuAw`=yRGQz=R@B2 zzWa}GQ!YPD8IqcTGNc5BB6-@WdPlD-MF>GMQ_`sO2r| z>v_RiRto`Ow-+C;_p%wS!hcA_cYvMqr=A7Ci#wsR8;v`S~eM zPuLEGH<4=C4&$c-P%^=-eBT@!Fo6;|d$hWd!#I?TH~R?yVems(0if>GiVX+h=Gi>arbAV?F1c>0j{Qd$8!ax0SXB$*@Hb4gckN@FU z_~gkc{`LR&-*G64aTd(8*k+d6CNt76Q>R3W7`Ov!@-b`~#c8=&wKD!O69!@=--sH+ zWXwtHpK(x3vk8s$GippP$bgvyYC+bOwaYitL=LtnD9Iz*VywlOqeKM3P}KKUY(}ND z6b9nyKgIC@6=>>fV3FbgjRv|QC5U9-^Z|1zm>r;JYp~Xc?_if}00(J+I)m4_%$feo z#nOq3rv(ods*)5I|Cvr)E&k4 z9&*MY-_IL>fnw8an<)c!_5Yb_4G! zaw$`#cU+6{%^8NOcau*TD*o7E1}F?vxD>T?OMwmlm`GJcS-Axq$>r)ze&PU%%*wSo^(RrY;1fz~n6)jXvLkK`=mcMJ!Ei z&bi7L)aJ34T-WwUIo;N0vteRCR9S_?n1jiwhRsvmdMlLr|!oG4cV8Iyr1K^>v8BLx6EjN2-Gbp;}4f zv=j@R!N%$Ui*7eZVW}z8%x=#X?Gke%#t5YWI;*U>>OpA z+iL4YDF)UKz;>Ou3;kf}j9>oif5Y_p0svR=e+8TeGh(c7!G`Oyo{M14QWZf3=zFSj zQCmZ)C~_tw7H}%YROkl+W`h`@de8wEUw#E12}B8%xsz-iGn+@64XRapdY!t%W>-=s z?`iqrvHoZsv-)2PjC7CuInE%Zuk8i<%cr1_pO1e zefjsY^s=#(E3+>n{cqbd-0Y3+bHAq)^*wQSmG7w-?(^-Qxds5%eP94!`X_Zhpx6c7 zUc!e4Sh`xbY5hI6M@a}cO||?gX60CGsnub@xI=C4*4}{du~HlWw9D;mpxsb2Ca_03 z#y5RTdwsg}4-4;yUAVZmJ5>)~U-j!QTG)PDNcIhN6MmK0$aj8$Rk=}TwO+13$c0I= z@Q(Nv#QKx_%j(0meh~f}^C3_JdsIMBJbtMQ73TM^7s&EEbIEsat>CLwyRg0nHA_dm zLOcH<#r_*L6Gjhi3-S|HfVuOTM4dgTN@0P?AqgVuy^Hy(>llTrxHe@qLhhr`;+}z9 zfSt?6H{bI*AoX~FssN?=+;ugF7VlehAwfx&eSd5ztna)-Fx>|cWpRue!Dq1-?zVpw zSXX7W_osBTrl~a`fH$;ks&Q|BwgxrR&N}6CT_UfL&LeLI$D0-{S_g2%8A@17RwGFO!R6!_6 z>?A1xYK-&tK&sUsRk9$(>LUQ4&hSa@TUvpfR289x3BeE3>J&!}{g`NdmVehP(uG2e zHbft{|FtfZ_JHt5LIL6mEDV35h7R%bk^r!W&%FfTSc6SaJmZqxR}?jQY>2A$Wwf=) zVEiqs@v$?LP%zqcKsOo4)&LGHYMlE;0Db6f*g0wFy)^(WNK?pldVpDL8#{nrWt)wA z>*8XVi&!HDW=#7T7jLex*^Gdi?~>t!C$M!nvT@ln9UZw)RBvCjlZDy=54!Q5YZpdM z=%IJ4hSWZ@}JlK##rewmN*M!MID1 zzJ{QFkg}42Z>sjASrO# z!tOPlQQaPAU=(AQS#qC5HJMC5G0gs&4uH&PimxxdA>P}b$Fdmpi$b>moIPXkXyz+} z3`n%Hy{kE^ZtMm)s(XL1B8m1Ja03lW{Au>MMAYaWGMgfo3u-Jof zau8Wi8Yi=d#*sADk!(DP1O)K z`He%(%jef-l9L&sTvDZs7Rd%UqtFX>fX!^IOJS_rfp0bUyA+0gJ=sP-D^PO5Sb!l7 zfHQYZr67yJyF>)jtQd&xU{=)~9$wt$wCU;x>e+SxM-}Coj(^;qG9G_C+9rlfC#h%!aiyULOPiol0&*7o z!|yLK`MeMIzZlP-f4s%dJ~_wb^&U{cWzLu`1Y_y|fW8s2&24NNt?%cYF$;hxgEoT6 zQ|J~knIi!M2{u+^SMa z&Fohkz*L=d^_>AmRFAxEahXQQr^sRqs$}755XlDov}#l(5PfT#eOo6=fU^kDA%Ve2 zgQs+MmQe{1t}rmzeAZGhxa=}qox|jdDM82q;^Ax-HFnPwtZBARCjiP+$H;>FT(7Ab zFfVEBc`foTDTLU7g5>jG1XIo^*NXGA8T-SG-IP6AFnYkoIYMHCxifL9>1uee$htmA zF2I^_ITf(kUo~}rR-c?_;{cPQ#hoRUeYFAK0@$jhj|Mj7!0zZRlKmr!%oDw9 z#RHimdJ_QIEbVo9v@b@grd9Cg0E+BKplh2;v)6bsOsMr#16++3m1|HbBSQSgLsHR9|E-U~gkj!S!!JiLL z#+Yp>c9#Yqd1@#X0V1`!%d8Zs0UH!_r7D1Cm{U4=f7={UDCTK~s9@ZTwhpsGM(f+e zT!TXj1e^xCe9dZF)%FwZflYsW=TD;$VHJ@k%k$3NEp+AEI=CF2`!fPKKhx+)_-;T zL}R_`bkd?QgPi>n>+fzYddtt4E!zEl?7rKcx4!4L&%aK2*XP{THxKQ%?_)XEw)Zs_ z-<9%p$M!aP|FQhA%Dd`;^?g4?IeOnZ^w`>T*LAe|dF-0o{=VzEx0OG&G437hw|)P8 zDRHkLA`qM42?%=cfR76SC@HryX_;}b80XZQN6Tf4TyWq8KZuE z_%82~OY@VU*@CeL^*R?7aIpZw7Pt)pXeGyYsj;gLa5d#D9AOYD-D@4s2NWer%A2kei! z^VbD}Lp?~{1+n?J?kG3Df7luvzWV+d>ib!HyY~~DPchXyt#1leZ(44g;@ z6MZi1`QtCd#jo(4&=6JtPj{c4SX7dZ!OWT<)`Mb@P7rq?w*AtS@v1JC9 zfIIhRZI+P;V%G*fx9V}kIShQ?Z+9&Ms_SRHrnB>+3Rtu1Hg~=2Xg^L~q;KY$*S2Go zTMbm}|G2jQhW!8G+wk*hRnK|=G}_l*Px%T%+V#OI=-FGyAdv8C3?u7-jeie}tE2@A zK*;>NFdw9O(YxyvexB_&7e#?*4DvIH=DPtX{Oe6UB4EeWzfN|B6@K12N`7!mk)?~w zUmtB0*twmEBDwqn0C56B9=dU`U)9X>ht>!xKaJJaX~k}KB}qfVyVkE9l2OzGKD;XKrG95#eH;3 zXH=v0SY;mCaaCZy#d2RA9=0xixN_^N^)0;rUCP3e?VfjAzaD$vZNmJJy1h;Pk412- z@Be1TU?}Q`ghdSWloC{pc>(0?R_@d{^=?&5YKNbN6eV;d+c{tSTNqsq{58N*`!1eo zQ7+5M@nGj=iAtx4Z6i_-va+$ntcRadx8#KmbQZx<6lI}!;yAVgxrMQLOfRj+M!SD* zl(t4-Io{px<0Hbj^=J&TL)AWD$Vti?dS3nf(7&r^jYReEDK;wvTg2%=DAxj=x_3t% z`%Via7XS=!CXh%+Na*YUKZta&7}kU1z23eF-8>@5L6K)`=gFgl&50Q(X=H4+gxyv4RBA8=F=oxtQbx=phPH#*$%2f z4p8%yc;2t4rwPNx8K=DeQ}UlfwVcf$SM>-9!m!~A{81QCYkQiE?ZPWwyiXI2<;BNq_{nI?Tc`7AB1Sa4@6#MpImWiT|DeAxm3nV5i=37E!78 zS%!fvSo;l_ZP5&T1y8dk)%ag-9!*cphm5Hd2m`0*CLfhq3WCeI;ML_G7ziil1NN7V zwY8E@5^(aeB8xDL37gXahl>g0W@)n;)}XO#?RH|Ud_)j}0fGgP#Q2~7pZ^VMNZ6jA z;@RWJ*o`wtfkeUN<*llWUg&@^3LXh(3VizL6rX-{irs#8rX0dy%76gln2?LE_k0MPF!jgw(A^sB7&u zV;YVjsT&Mi|3daMv;Y$sf4rFrh9l_EAim?F2h7RQEE=4?DvRx}=6$!wd z=`Lxqq{g}wAXvkpIPjDSB5mWb*d)Q`gOaiK)n#8jD$Ua~hTdsxUDEB57j{*M)qVjOF?6`lbUKhemdw^;gtCXG9og-3ajb4GIvp!%yo{2 zY18)Z)TIaZSrT9kuW$)oA;n1QaolIfdgQddgFr zQaCGu$u*QvZ-gtTXickaX<@Z8_kkVEECFH^uoz0c`99s%Ul$GqVC-Wyg+h+uZ71(C zV<;7Mc5F3gSUknXSX!Nf5syn}SH*a8mAlaICc-{9T*pfQn20R>HWvdr!dWPp>sT+E zgU~f?4!6`tF0E0`>eRAB7T@pul_KF#abR4qmc@JAj#6iw z6rtMIVEhc*yNH5BK$#$^AkR+!OsF3eQkS6=^!xggkn!HKX2U;uzaq+sM zn%Hh*qX8*nZku|t3r#NEIHb@8Q3&TBe}=2C{)i&Q^qaaZTGM-X)7W)|!h-`shNX#C zFe!@|bE-(O`27HIi$KK2tM(V!oXI%@3Je2-oOMFnmQX|Fcc6T&V_dE6(psaYd_LflFqqZyRH@=Ts0^Bt0cc7lPK>EAf-qqW!tQ!Z_-M$DO$OurY zi^5rcmTZMm4csH`v@39PjqKiq@W1HsE(_;O|6OID^FthJy}52!_+;XI?D)Ff)%j>s z;`4Ui6IDa^@y%zozKgNZqwmFy&$agtRL6RJ>Dfx^*eokheYX);rLAefB3CmBKrC=d z(4ML281&sgNdU(lfx11UIKYtrl2(rhyp8un_btbudTIeQf2aAfR!yef*B|>5>JH`z ztnufX?L*w3+kMhy=ZL}!OkEGmVhi@XVFG%fsC4_UTXl!^CsFvxX!UKsH)@3zl0mp} zNUf-Tkm%sZDpEz~J#JT)JFJ)p(E{@$0)JL%7ZtD!5w^`Xh$shwlJaUB7_>{MNnSzqc`Sm~i(Qx;_Mv zgY&%qnHSFks0Qt;UvJ}Qb?a3&5VG0EJ%}_Iah79aZ;zsu^(UTNbzi_mTR$5By6-eu zyj)!_RqXsY(i^LHufoVe$i0VJ)XuhWh!+bimYV>D^k* zb*E6(At1N47W&HmP|w_VQ#r01MqNKBTCQre`PL>{yJuZ!-S2l?`<*T;<-aJ$Eaz{d ze5gJ>A{!sP+}D@KzJK8S{#xa(dVTXUJQ zG^wHZ0spD1W-8ixL8c300j30J;#gh-GO(Mt?ntEV9ojG(@h&3Q`*1)@*7^)HX z8e^I*E*cBB-_h0`Kag?uKhK)BY{NQ4hG5i19x}6;7>9p6|fs`QEd`%R%G^+ zeqW<#0UqxLe0F|{e@s`{j3fTT<{U4l3I8x%flmg=bp{eZrv%yw_oN}JA3%~K&mE|x8qIzvMg_xQ z&q!>*qKlUYqwMyzalb1VwgZSQl3_d=b79zYRb<15hPw&kQ^$VxS@sfUfM|doHt$p%{DJlx;GId%1)aDL_;jve0c3 zfXYl1#&WPA8tx}H1B^&l*v~yhqH@D{Uf|>H34Zb98FnWbhl4Rl>4{xunSCv~YD@*gSWrf_xu?d$n27L;&pyU> zGvM*#Gh^vYgft8WJ~84;c+$tZ){#F0V5F2#+&$TEtO96KY3f&Nxz_P>t>Vfvz@YYi zb)Tr+EK+>WWlWEanTs5d*8%DRXzI8f>sS8?sepV-|7ZY$3MLE5lNJH%HRv3{wxQ(! z{iqGHYV?mY5Nbr&`um)@Oe(M_AcNk1Pv@+)%?2z{h0)Jnmb#WlEIR*J$?}kXXF7vQ3cj4Q=kCwRKKFW)|j#|9TR{Oe;)Tv7)6!Ya4a%8t6_*4 z`!h+v#25$0=&3!cJ?C{QVzvhXC?Rub4jgNv_-CFPp@PU5S=F;rw8<0BT~SMkY-_Hq z?I|TN``_?r%VI#F002fbd5d4QVyWKUcGA$r_LIpYBYljDOJ_?}ZXB zfB1dHe|NhWQrXeM##fCss!Ii|R(I1y&Oqt_LIF^6fH?eG5at0X~n<98LZt-Lo&2A9E zIE>hCM(hrIJm2kceZ9v&{p0Vj*^Kz)(`RPSy5m(`FNun=s=|Jk;(g`-S^*jRCOZoz zlY`4#r@@`WYG6$96uz-O6cMDDOVPhYEb^DlHb7QnodJ-|-DJ+d<$;{(`~deE7%+j; z;3$A8nBPSrn?d&@qpy1N+|Rp_dM@p;8AXjg79^OJXmKKl7Z>T>qmb0;>s?V zUL&orr4N>-&k@gq)unG+w~o0|gkT1=MD0*{NjqiHQiPk#5gNczDC|Mg=L;aWgPkLw z1im_^x_?#6ybUs0PlAF1iimioI#0DaUEK!O0Ot0GYRz`lSTm`~|H77DD8t)I2kKn> zj7@moxBd56{jEnnqt*9svUUN?y3O2KtjKFe~%vd?7LRpcFevnWi6L| zdFc2ZyMBFO{m}A#kcA)1H(S2$-1}3VyWdoK$f41(dAq*;$1(V@<+ky;$9`y=Ir~TT zL)0y6x4&B6s_3q^y{+?ySrDNsQs_4%tcN`W;yci+rlQ&O+9 z!u{!$0)qUfR6kZcgZRF+YY6~>`$uEn3fR7P-B<1U7WiB(_S(q~0OZ!TKDBE->fwMT zX;k5snl7tB>o2>WjnD3?di7rzX};CC19L9lwETQI<_e+kKcJ44`6n7!Cu&&#jIEK^ z-F%3=@D0W98XJe`2kARP>-kgkih3OhfCw$#Q|laOJ!-OC@iogXv~wynV37H!yZ(qy z_B~7Ue{{j0?aQ6@maH=E1F<^0hh( zT_fJ2+*O}I)+H;kk^)P`*XyHRw?H%Bb03=Z$wfAfBDoJ|}Z_I!y#lU%_Xu!F!^`oxGWTkIM-=46pS9`L2 z5Y)gjI3U4m%+$9r03Knqq8Y7j%y>3NYwH-#cc#P)OAQ(N=a}sKni+i>4Ak{ISN;`n zMyP}q#ENnBgTc4evt9XU9P!s@kMPlEi%)pKC(jSqo^0_~PoF?ladJK2zi##b6tXKQ zSH%tiM*^;Zvdh>!K7s6t20up+ZmxjrMDP-<%S_ zcSSo87W-WTNUFUE*a2|K!2YUWnhG90IkCM)QKapFv>l9f1iguI*lAkqd(1Q<36 zo3ky-VMc_s1nZHpDiew@h!jEqi*{f%BT*EQdSKT_sKvo001u`zV5!+aX7p`O7}swO z*ghJ;iE;9HW8Y_M_x5}PR%71Uy*c2?r)M}h-$D)rWmcR$Il-IfS2$eFIC-|kNI=;a z?A~MyOc*xyPSr^93^(LGWnXC^%YJ+msDKiL(+DP)`JfPL=_aJ^Y5f4zH}bLJjqGG)ZviS2b>_*9!<>5-=pLtY85&UfZKlj=5_9U=~ww2tXNH6mu5L*)|-afXoH2{&0=+k2ZMnvooBWjktWV$D2Q1gBdt|y20Vn($HzeDcv_><<~a zWR#LE%>~n(k#k1L1#`B(+wBi{>EMbig2SA#pXbU1Hf3W;69OU)Wfo^{Qe$pA z%ozs({^GM|`1QZ}IX?gW7tYWq#_l#Gkh4;0jVdBgGPW}*#rMszN$Vo1*Z>nKHbz=E z9(R;(eG11)N~y|E1snjj;iHgp|IE`FGIQPFRbZENzcUPc(SHY<+wrvOwsdwmsO*PAzJIUw zO*L^)Dr0K{!m2Wwba>0d*6ZexlK4C`hBNg6Sg>q*pH(PMq!%t3QR`?&9o&$qFoLV> zDU6~v+R%@?kAZ1*n_oWGrSwomh9--OEzS}u+0x?L+_5=p%-K`{J>=~Pc3Txf@pYuC z9kq2e`XFRRyw8e6TxNI76Lv)BAP6?Un4n-p0oMSPv51?g{x8ZT(&Ur|n;WFbfd~#RG|w1DB~j*Y*>xlRH3R zQFkI&Kx46bsbBAUDP&XJajh|b#Pr<7>nptc;su^;w|G2k@MuV29&nv4W&Cx{7+^sa z3|r@hG$5CZ`Ax=)S64WFc8*U!eQN7zai-4DQEKdrX1fYKu-JMKQfJQ9WPns+kVFq-*6~1n`ykwb?i(uen>o>LZ#8kn&p{oqc-8)b@`5NmH+5yIk#X=Pka^D^aIcMt!c3>|kBDlq6&Z5q>YaeH^ z^ezCh5Qs8HCKOFz2lY}3razzaT7jSU_7{UP&c{jP_~ z{*UE{Ro+&Xe#qr*=ktep_e0+G<2b(G@^0fx8ux}jsr??dDYb3ojW^m>TWb){`m91@ zA4lx8WXo}101SNJ-att0yRiR{7HvPwPNce_SGaE~d^iy~1wgs^bD?M;jN8iU^+e|3 zsm%Jo-2lM4N9%lS@ldyS`*$3jQ53#`?*2Q5{vlRpeZK$ac=dgEDdIk{;}7oH{Mwz= z|Ka=Q7!UtD@eOFrTv9Jzmj%!aZEzOD%^ky-boK7%c9R+Rigo@e*j_VKOMT_)-K+QB zJ|{w%Q5{xUJgf6X#pRHNFTD1DU((VBfG^c?3wyKBl_NlwpqaaB5G(yIkB57v< z$Hpqai(Y^3JQxAk4t*lhSox}SD{M~=ZRZi}*J+#ygl~B%WpQp*{l)IrcP~ClT882_Fga`uJF#At*-*xZO+-|S! zN&XLhSTUn9oe2yS7j-53PE!YfUbiD2ygtKN%gq`9sknI$fGH~=%@``xSTKbf`jXP} zS@j^+>#y1S(XT6(MXu`YrhIX?d$UOz09U>Q_wwh8-#;QXUga5AQloMXdie=AIm zA3Z%mVzxBS03de%+2a#SZ#>%}`{r!K)hxJrGvn;h;L($8AWRsLC?Cv;kR92^N}jgW zMLKqBVj#977hD0E-!}1`ov_9*VK$|#4va=;gjjoMD;V`Ac zP`5}aS0^RFVGo}n0>LCLHr5Pl0qrLwX6!vhVS_>e(_|^+V*ZDY)dCD#M$v+4pYhXQ ze}ps;_Lm1d{_GUPn4lu~bpcXUKojzI_pl}+x z?YP_RakUwdJq=x+E$w#68MzqyRCczz0Q}_K(jTjuOcfDKQ})C6h-_1@ONgGLOc|nr zLl*2x!PWHv&pvvF|NLM76^b36zZP8W_J9@#3)x1gpJ36!YbsL^Hz>Dqa| zfnVyZQq(a6B4XBGTJzPnIaNW&KD|mV7-_(l&tK!K7jHmB7>B_&nG&)r4wL|%JU+wY zN2eVVU$nY6TiDfIlDW0Ii3j3O|Vhsw~Qo zEj0kl8PnJ(y}!HYJ&DCFWYFuz903#rbvgEB)~*dZD*&xT6(AmSOC3b-6<^pi)H{Dd z^tyGXwyP-MsaD0G9a37I>hTIi1y#pMo<#}UsQw0Dq#RIEWnz%Q1sGHs9c&GJ*k$L#NMKkh3$= zTC**^tdFS_wa+Bj8XRcmdQ=D?HGP#!L7r!8*F0k?GjiS_=L}*XsckH3`tTSX3jN8@ zqGo^O3>^kQld~S04I&s&L@?)qc{WzrVZ&h9p$>cCOcQdGrvN&N5)u;zvY!w@@@y$` zPX?E$kO4Jtpg+%mcAaCA7;SUhF)lm9;j7>OGp09hAW9a{p=Kjirde%3+ZuROinDL3 zvoA8zz?CgN*sNm?M&N=JL1ClH76(UXF`YRM44P*QiEUj$h6-0EaS)K$4>&X!k6Rb2 zk9)OInsxz5-B!La?Qokz{_To(|GtUx-Era^FYnS1$L?8w_O|Ul_RO!-ckAb^$NXJc z?!HUqeU07v``gC%uJQP$=F^Ym`(JL8m19oS_3y_HC2o7h_qDvwx%4*Ay6f6^(Ft#( zFFxeB-6cQYh4L=;hyq9$H{*?4RcwE32jYHh1uOLz_STf|w?&~fpwGYY{Zgv?;$?qo z=Mb;JpX%pqL1XP@N7~wb6vqmg)|a&XB+ z)+E$GLz{FT$M$gfisQcCWl!HPyLCot1CQ0>z9sQ}Wdvc~c*ZeQK!0JR-$Z9k`#vK6 zu3KNA+uyVn#Gbn{t0{aRm+JSCodEElDu3v);jOIm&TP*0Dqg&^M2Zt44N0`-i#!!ukt27_{56!NDx%=OWu@BmDEtFITe^`M!72if7bf`l}?DjbpQ>N>2Ioi=mFAJ*CyKq<;E+*mlL(Wi}d5}8Mi8aHX;Z=i32J- zp}Wyn<)*#ggGrlqi7(BE5b9H$I6?xH>cMlRv>RMPP?_FZb$qXF`{>Y@Jy=cwi>ypd zZlhMqdWICWXE!lk^2*iYWe4$9Xkg4EHTkjm+dYZe^OP(*Qq(H?qlkY_+M37>D9Wkz zu?9kwg2m^E4OhoN5gD_@L15L78bQKnotwPBv;$v-PqaRrsIt%j042-N6j`Y%E|eOf z1K0^0YQwElm|y{s;oA^YpI%db5zyH&8#*vA=D040u=+bW>Z7P@S!D5o!n1Ql%bJh9 zbx9k;NbS4mD)nz5GDoyCDS(Vgu}>2nKs{~a2QmU2u4At*FSQH7Y&~9F zE-izG_mtW>ObA->41*d_L?HuKJMlot=8FRnhBP?SXXwTzVQdE?h5?APg*vv}Zivox z{}@$A6k#p42B1YVSgIUX$!qt946PqhI})q!njWyT3F*GSMLTv=izGmnu^_Zs*MWG5 zEquc+AwZoqkyd@OK;%B8(2Xv-`Fp?4JoLHWWC=lfh(Do!CF!Z+q5W>jp%3m=fTN=eo2Bsq% zpZLq&PMZh)#%clJ>59M)Ur+&V3xFVX|JLK@On5bI`HW^i^gzWh*a}d%eO4F$`{wp- z@^X(n$!y=%wTNLXhP^zxeFZoC$?GEp(0NtASWC0F>Db2gA?@geAOL@*`@BEw_H)rp zKsv$K(s5Y?hn#WXghLU?)eP(u<4jOyP%-8|+7K`@Fbm`&1E&c%1E2(XnSm2aQOjq^ zKysG_I7uj1f*+h!NE}H?(jA3JJCV&F04x|eP zKLa7o#UjRr4PkpW*mNs`M1&mRQNUzJQ6ndTj9|nRQCz;*yWfLw@_4K)g_dg8g!bg| ziEX4xIEXBT@OV1dwQ7BRaynw(7woSN&`SdarfaIeLMgzs6Qo2azQat>op3|c&r{Xs zLlhBUf0;dfAKHA9Fu2>nHNg!1nrM{l@H6bjVE5@u0Ke3uPl8??^%?d~6{)JJ(U8kq zuN{5l8(=_Ll!8Gled1a@Np>A@^FdGro_>0Uv!`3k*9Dn@@pQzee}0aumk0d*@4v#? zvr~Nbmrro{>HsNHrR7*`m5bU=LUk~<4pa8ej zj;2r|bs_xOqQIOp=GhW*idafe1u($UKx+x-QZP&@vf9D(jj=4let zIc~c$@Q6|rU%hyPF%96crBQ{m5Jf6U8&;{#1q~T3Hiq$*8l8y-0)fx9NYh&}HAEm~ zJb(Tg|Mq|UOMLRtV;l}Mim0(UmI5hapkxrv&bBx^-5?k1=U^TZ2akqxayra-`SJpr zF<}_k=ev2AD#>CnEs3Da0wTe0fB&ViZ82dO1_0y{)~JA^7R_!fS;ci5X*e!}B~}*B zEDi-h+N~9B^Lm(#fm4fGDvF%3KTMboGk*X17f=UmqzcsV$AO$>(E2tJV@On;BAw69 z!5dOH#tOwe7fkb9g@Y4g91>D8rArEon-SYFRp%2kgNbmm+2HY$GZYexiI4`Wjs_D; z`y~K?t;0~GCoIA7E;4z*N3K<*z1yaTJSJgeJ zEWFa|`f6YDLS@%(l#pBXd;2dHJ@~C>p+mUy)aQ-H&_~p*wvD_1N&)C;H3;@oIM$3? zo(dqbrCsU3(PT0HD!L;XL&86qP^F{R8UVD^6D}!PpCDj`KNS`pW@} z+8m#C$&6{_{U)N&NbMYB?_f9yAgvE)?bA4f&{*Fa;IzqoM2a4_^CEqU)mgkv9l#K% zEY}e!PHZ5#n9r8-*&=hKu9Mn1;e8(Xc=9md;`KGk^&UJ9P-dKOH%N(5lrV_t;cXfq zsu+?vfHv-{*~ox73$Eq~^YtEo`20EYtT=yk=C*r`0V-Iz^-%%QfM7zdn<#a6H#f#e zb)cDur~Pn;ovMQ*=h>rtOY19*x$Osf{%Uis&c^iWQTO%WDfFd?<4NmrU?;0?qdLfr zib7b8>YA;7sn}Ybi~3rgkyFB)v)gBbMaz@1YYGe;J53o`Jngox!DT;Tv)!7Ecpp)> zfebKs?9td|Ddy?YAtCMWI3NorrWmL(m?wi7G~`^g80fMHN->)Qs-8;O*;nE7++{u1 z92F0wU;<`=Ci1z+C}Pg}X|ltfQW8KJLe79(6uA`BP0YYBn2Z$h_116%Sl(Z`ZLYkp`|i5# zU7fsl-Mha2N4frfmWRmKF@64H`S!|PV|LeA9lP&Cj_Y?(Zf@UW+*cBfc>d)d@t^+R z|H*?etuPY~hXcNR{&E2T&||MT_MyVSd))_>{hrLiz6nIrn}1fH5YYRQ!cI-AXRK>t zb~`*Q*gO@LWgWf=j6)8DZ{ns^c+<|SJF6RY4%f>1TwA*~uv_#;USxi|8|5Yd5b!;7 zO-mYWSruLXy5=cc)}bB;MWE!-bv?n(UT`LGL_Wscw zl_4r_3V)Wy{>M7p!*1<)r3LhwugrVk*6HGbP!KRPnoGY_);;sR1wcg6QdM`Q@AKZ* z!100B>zW+3{X~5t0Z3#CA7Y>5`)e|{Hxf|=tS|u5)mQ{T?-sQsa90BQ91PJcB#)`3PVrYhDZbwE-C z9Cq93@U5DftrORq>%Ncba#A$Mq@6h?29y|mrk>2@c5V8=+1I+GyVx?hP+-Ip&UpyYD^3WheK z0QF@uSxwcm+&p=FhClz+Px1QICB`w~&BZldy}HC^Gu+Ubi3$7tgx~z;3p{x|x?pw! z*rRo;(qHPPg#ud-YzS5rVqM+aua-xE4|?O5<(JyAO&%*p^_Li!Uf0*SlA_z**Og<4 z?VDn>tm}s;{lxuR<-XPBU7rbH;eEdE+V4}*)zA0&%yoHRV{@kk@fOdyWj_7@%MAcv zUj&BBOYp-2LoR@!mQqcUr`c=o6MF`~{-5CO+Yr~!U47Qi=|M&bC|3?@e9N+B#!q-e zCdK(M;^&)F{BdUF-xZwAit~d4+bu8|uuNxkI$3Q&J9x)z2-u5l7@rO(Z*nvGJN=;o zh}N!z~Xfkg^1ivxOKAb=8^1-K2D9FURCI6hoX;KWGh2{MbNXuY-$OJ^g}$zW+7 zi(=f41}-YrzG0IvY!asH84SjFHez>qz%(mPPX~;Nkta*B7Mn*RK(eu_2?!+%@no-S7foX8Kh8|&Hrs?l^BBZxKj^zjBfB)1xU5hPD z^35`>RJ;P38>d%|?t_8{+X$C@gmF@Va=3jkrFe?V1fx%&~%vda17NU`e z8k3A0>t@GU8#ysZgVlu4KsNRteh&*`2C4(^M!7?d%Ou#pp0PO@asG6~csgQxK4KUd z<4MA^pPwU78N`eypPYgR#`a{yZ~o_N%!g9JXUtTCQ6(H~YU81$_@Tdol|dAYYbKv_ zw)DT6rQ7FtAE|*WMd83xlgBw5ko7QU><%;LoE`Ymr8ljBD=Ywt0M#{06-bFO4vfvJQex?IidOg^oIFUu14x24_7*GVrk^v3SuK^vx;YMUw$7wFebHOxa9I~Z2&T}z_ zo#eFpFmSKFL+U;om9b_Ogaq?&d$OGeHXy(^_S8>FRf z3>GM<&lY4Y6|o!Xev4!W>Xi!8fv55n0baho#N$V&_+S6Wzs33KDGqZ+cJLno`0c-b zi9h`DITVUFudg9+mPiMuh?tCtGo2j{2V7iUA+e3Q^?h+bRwRyWa>4-0G~;)lKgV{n z#p6e(7{?KF5l;o{8!eE7kZj!v09Du;>XRaXH=!CsZ<15@SAdw9o)7b5+>F)ta(Z%t zpa0osPyt@OzQmXkh|MNTk)F~gQYpU4CIOSRc}OieLFk8;3fT2R5&ZHOKf%WzJ;h;~ z>N-~SxXS>OJi;d>99uKRN;6`q4pSP)l102agglO3t{vyf#NgM9sn?20;eK zOCG72h5==s9pGtzlf(&^7nj)WcXeHeRNR)L(w!!Ks32j{-kKI^ReCdkT&JK8D|O$( z!H6;7E43T4K`|#?ABE>Tu36vffHrFn<7B(R$=L}+1Zm)UJtz1^K7kR@^$IDu>P!%W zQbMXxtBOM6I-#Yn5r33Y^C6^^Ed6z2ym@npH*cHz|$Yo1e(=?pu*!HGH6#>%J>*tG>5jOlGO@k1lfE( z%oEPX0cXRA(~}d7L-N1^W93u;o0M>}-P(Gm7Nxz*8P8w6K?37!81U6@hdls#`5I52 zJ_2z<;o|F=9STMCvnnAas=#Xs2GVdy5rI>(RJmlhuSDiJ4%XGI2AEc7%T-RsoI7Xe z7Cs+?y+c44sxAcB>s37R7Z}F`^7P^a^`M$$HZyUHv{%!$!RA=hf<2NZb7*D(50)z1 z~k z)siPdw zx|dZz3nC?Vc0e#?0w+R3feJe_fdw7RIlG)%^%5rxDkuWXMF0pAGX~f*BF#6ExpxH$ z$$n&54^rBk7c)3&U8|1lFC(C(ql*vPGg|+JW3F@Z)}QNZ?V6AFwf3!UaY1o~1MZil6RtG`hsOuZz3z{pci& z`1UTVLb`Du_Yvpo=SIEz{r(-|W2Sl6Z+%<3k1F`@m>8=EO?lwWF}A<{vm0NN?FoAx zJ_{f+-&$?fB0kdIRWS$Jrza)AGf@?iy8jPfL96!h`4w9xMg*&N@A6AaicdW5P} z9C>p00mXgPWXAuAS_;-0Sm-xU?EU(OFjeqR@VmwIseX*EWrU7tiEj!WThMQpZ6G{A)IEy&qvCF#DK~Xqjn|F)#T~!_ zWMgLx?9O>ZO;{$1)UnA4AjX^*KIb@VQgsH+0EDyEMI6)>-$l^5`St*EU|q$QS*5^i z=N^gD(tX;wQwh`oAa8Vk>jYrIY8P`i`oF5h1sKugOT7*CLGi*S3x+$?UM#CmKS&@V zt+D|m#nv2A6fI~on=C_xxfo4;DKanFI$42-(Fav1%n4=egal5}mgX013evsH{@jK4 zBBnNczAW@kdtaO%RpAQtg?My4A(o%!Pd49KeF;ir+EGBcdk6vKfzP!L>a39A&nH3x z8W?b`oBUwVSW&I7D@Rm}83+`amta|#<~if^WP?Y)_!KEIKK|$lem8uHSFbPqT(x!Y zkOsVb@e*SK{_p>n|3hPcOnuKqKdsgm>FcZAgl%o8s-sc>xAD8VMjt~QKhS2pO_9^; zXH?03`-^*Hab8zrIj#IBxBgfMH>{3|>>6Jm`^ER`6!p5+I=<~Q^~mqkHpFx818Wu_U%&lJPl)i#@dSUqJ;C#N zkISno>@#6=`Uo%12mF`)4u5xcit_w`D=k1G{Caba)5O3Am^Z+G-CaN&%!dtuwgf$R zWZ@}W-4o&FuGgFRwm?)YYuItx(V@b<`aXaJbPtTC2jFa;bCx7+KB7F`9l9V|k@3W=%+e_QjQcLGnJfbMU zH~wnC*PI&zViv`$g56=lX20`va0V2M&7i0viyCW>sHLuyg1HnFwN!?sDCQDr4He1^ z32Z-b}U93e2OIpin`a4ygp~AC-`^&_OI)PO^O2x0SE*#TMADt z#)fApxHIOQvD;6$ygp#JpDlG~uquKauos8!wn?4xjFO${$Jw!_JmKQ{52QTzy0-Nh=`3FDbkRzJ=tP=vH_MF$K7EXT|L^}6 zZ{A#)oG~L(tVs1fWoHRYmcsH#sb>dj0Kh;0^Pl0fPd~ymdy4aDhl4;=)xmuRI(+r= zHGcp3ml#rlXu)Bc!2o6^B#_M!a0Px8PhnYd!IUQhLUkL_(2wjOzLXM}ComB{{^$u# zwj+pvi#J#J^7%{TJYyJ=0doTU$80H|2WKhl97-!!;KCkQ?D-=)J|gaqEiR$hBHFy` zpW`q7%`Y&FTU=aB6(FQOk0J_PiUFb%lj}*C9#J^p zj7*Q_V8^t>7I9{`24;i<{RHEfu-onM$3K3Blhac?efAX7oPEt?m)GL+U9j1X*q&~X za{-HhvsCB37Og3N^Hgv+>?=?>+Rre?$@9mLFeq16OjX9~*O!>5*$!tEbq~@zy5rEu z80Mt0@A(b!yC~`*M1V5c<(iqW9Y>s^Tt5r+6aom6s<76E1%U}Hzo6Tt8{NB^00JK0V*M!u08wZ!R-W8M?D9lKMq1>uNUDVbh ziWDSfdkn*f?RJASjFA1_u2FWMp`{8oo6@H|O!xfqmsZ!bN$tS2DUF!yATVD4@n0}q zURK~=bt)HW3c}|BNNO;aXG89kN^5fqRA}R=YPQqJ2Ko%8NX{H?U~K_0V|KuOE(uwU z0WjuE;sOn((yFukdx3kaW8K#(Q+1BsS2Ugxeb%>e{n?+EL+1YSLu>E4{LtF}q1(GY zEm#{n@ALg{`>Y?@SpU$=cg2zXV|l;jZO8S#>yI7A-L^^VzhB!F52?p7yW_sn*Y9ne z@fI}l^yy=K^z;cP56V!dXG>%m2|j-Iw6cizPj83o{l^DzhAJ!|-F0riOKsP;KX1BGqisDa9M#VSFuxa3t90kGFhTPy zDAaU;{SZ&XYG2-ZcCIEx+*^Pc%wlkiy_^AJ7p<`QCm;NR8l-57> zYX@yDTjAjB6;okkR*1HXc0NXp`C`5y5osBMa{OMv#r2LK9M%AOY5uRJdRR4L(P8ap zWnoz zAk+Uu7o)svZ@o5xipkfWK49D1#{RGvXlc5<3A?vjsisAba}|R5w>S|NtiUm50OmR4 zFaP2v_`m&M|Mxgt?T_|4Xp%nc6n>WxyS#Ag>1wS32 zgInyQS-g4>U~psP>wqioC}HbFk#cjw8!I3oPZ?>OuzkF-8?ys{BCYHJIQ!TRp{J`E z<4MB);(+b>h-q)EhTGG@jJ2Ye=FSL4vt58@l&Xig^n{%mXx^P(LDfF$HkLr8-3I}i zM}wy<1?Jg+06a00CY0GX!2>xs0}E#i0BlZ2%=?TyOWjznO_I`At-Ck+c5TMoR|u9a zF`{TH0~ZH4%QrB|k`|IQ?5J^$IG8LEk`RXEKm`FrQ;lL{2C||7lqwVAIwJ7xN&;b| zFt-)6zCDpD0PHU(s0hxUZov#Z`{_CITp+W7kMiMoxb#Zpj0BZ$_);IzX!kldv z6m~zvjQK29$K90i=6VNEqk=toN>BxcVSp+yPZ`sk>*ihdicddz zf}ei&kx9Q8!=V&oC#>nX5h*|$gDN>AUU4UYxKp6aGYZ6k99EaZ;ed-bI|B+9d)|Ne zcYlMApFY9A{_c;s-tVA-3br(WleD%uh*0KInb4{u&)G49!OHs9$12z{bG8U%4WM$t z#pM+qKYnBYj&a2Q>OcMu`0A@y#n}*Tx%*j8{Cy(xPQuZOM+AK5 zln$_P1pubz9;<6y?>N=a|Lv<*hwj-DanzQA{K=EY`1vn>ip#4RUw*aoH8?}n<^*7J zKJE4Z0jFnYrbh*s4hC*5#jZb0xw2RmPa|52=>QUd95kspL&^bqw#A$UAAR%`zxwl^ zE2cD0D7jti(Gxoc^4+VKWU_i9Qc=YrU zK!iC9hBP3J175s%jotMgX=p5wYlmSQ>~7fm!<)`Y8SI2LdfLB}T=3Dy&+xNf{22(q z_GE+CZ)O9i7XvP<0uVvb37P>6Za0WKAe}KeXJc#&oeNbIXKqz7Hp6Kaq^x*)eu`61 zGpjC#+s%l9O=n#lCQR9w=u{QEIpa_S&(6=B$@&(#;4o&h@l-L42D(1%C+x%kfa+<5)0ptd$4{U{$a992f?-fReS8iP zi@q*yG#JRvB2V{+14zw=8pZ*eVZc0P{O)&O+F?yfmcojFAteVVGEPn(;nCw$91aEZ zEZFTcz!uTMi5wU>AtlE78R2SIkc;9l60pDTaM*eKZum?Wy85>Au8zL%dx_5Zp)lV4 z5XX33zUe;rvCn@jKb9ZMH&x!&7k2FW+n&+e35%19JMQm2ifeCVeE&9ed^cZTus+xG zS3wP8+H6LA_Sr`j9P@wAT<7odeGNEIoJ~qHh)>0$vIp!6<`Ow;)aD4ZV51)Im)zQuS zVhooUfyj=7rEf#q?9=sw&{?%)M>T+Vg>7J*&5O`}sDpNHGJo{5H6W&~9>FNc9RR1V zj{AMWUqo?*&!8UV>g<0ty|T2yQ}y!_EG{=dV6?k<%PHR5>Ip^jyQ)IgK(G!RrSU?q zcumtZSPPZj^2ZJEpYI!KC3oxdJBhAa zNEI!|sJo%xkH=W5s-G7loU&MaB&mJU>Hd zb&(jh0M&V4kqB;p8HvCZm>FYa_0gL4u67(MW2Ln5E1nf0{s9*J8vgWow(Lc@m>*@a z6nLF$S9z8U)PA|e;}8|?(`u{f{8Ul44WwtujvCnjL{^JN_gJy{9&N7~Nh&B(s$AN% z^}{${LkRBo@gdU6nCokMfF8-uXIocP_l&U`_BzJ?4xdwEzS$|!XGGuxmxp9$f;FwR z)sqQ!J^>o->zhL+{Vx|KZpG-1vKhpYXKe(Y7sa+$9NQ6~fJ z0?_8}!c-)n*V7A;43vL0*6Let)T#B8Vv%yEz2xrO>6Y(~31_f6lCC1{e9r|(ue<{kjXNV}#T?2$&RqODp{ZOdMBm(jHT{I+rF_2c?}y5sw|EqBPpJ3s58 zZG1?1*YIDc|7Y)CVr|W`H8JQLWB&izd!JWCWJX3tM&6q@ z>t;P~m5p5G!i7Z(A*)0OA%U=DjG+N7KuFL4*$o;X(S-)k0f`2p!$We%Mk-Ol7L;5C zw#$NY)%C5L_vSk?9w#EsIeV}5|8tH(V?5^k*IN6WeNLRnjLdsx=)~T8t^YBfV~#QA zH@+c?^}2!zp{gHdhs~kJ@~6!J63hUpVtKlv%m%_JJ4=&xxG``{nRw7k?Cp}ei1z*7 z>+|U01N`3iekZ{rV__y-U*F)5fB2)bbx$$o#wo}Y(cOdDjHITP7OuHbSrt+&Wt}!- zS^)u42xTxvqaUO1=4r;o?!uM%Zb~vUL>2q}%{lh`(@2k7`agh>0zag5T7Lr2nYwzn zl~7#cA1Rnksb->{k}&$+Da5T|aad|boye;T`q>qBN$1C_OWz0IxWe1--^Yi4{5jAR z58k=7!&(4Rjd^XpoKT8I_AWQhWJYkX!;v1mn0n7{B$UZ$!y_xWu7YK$xS3b1OUu5C zkq-x+sIm5`Tj1m!xi-Om9ayWp3#ci|#HluphB6T_F=JN>E|~D_W{+s)BG3_#q36Y z_JgluZI&8D6->swYv3qPUkNwf0ywB$xRDzP@Qo&EV$Vpu&fJ~ zWp&mxAQ;%x!IV)SV`E*NEir(W29VTXDO4DcNCKFnSZgzIjx#VZ0R;k?3YNo)NPoG% zS#a2|&den4DCy1|g|h{e;s8K#!>PN&N8jfrf*5X;QeTDAYG2RB3pT_~N6oELKXszmiSFe{gPv^_1wPIOUObWdH_FH)Soriez z@ILN8e296T4EP$3oI;i^ARSn}jS;E6p??L2R3fE&3mnuJAXd)5Ek$;2gaq{b-Diq7 zNStMl2@bp)94=vGCX=K)j#P1dv&Xu+w4m+!Wq>X{kRWAE%QY8mXVPQ>3uiBf zaX+wjMYpup@aWM4+`o5)-EKy$EAHLD#Kpyh&nssvn+Nb~6R3kd)mb)koU1W@Dg=e# z>%oA?bv0)l!GLczp8(oT*j?=K!FRs}QDAp5W1c6>yV=)s@8<4U+&U99#>wY?rYB9E zs0+#3Djq(3fbV_p0|1KUQ1Rg}_u#@1v9-y?#;G-%tJ7rZTBK@%cU2X2t)1y~ZGcB4 z8+cj3r5Gqv8s52o5AQyBh<#n{J7x!bSxVXm#2_|?M2KJ(#TB~)+Szi62yb6pVS!@z z&A0Ha_rIC!#2V?p6i^7(wVHfa!Ows3F`j(>6mPx%5c51kAqgTYbHVKCVn7Cl)h0Ig z<{h3sd4^9Pe};$Oeg|(odH|^g8o&JLQ{20Eg>Sz5Hkb+f{feLc^h3v&(Pm z_}!&luhRC{(O<9N6wlHVh>jdn0eBey&NrOA#%#Wkjs9F((qo+}tmke$cAIJQzN`cC z>do5+11-~5I%-f|jj^C;*`^L9?U_GSHcU|ck(Bx^lj)rbBs=_g9^btpw0X`6V<7x`{^qp0C_-$zw==dy8lSb(dg|4AlvlO!3Nmz6a*xr(FmNg z2Uv0eTd_I62EWCo?c*3}?Y|Eqh`1nG6-DwpCeGl~tgF{Svwr?IalhI*a9-SVd=Qg$ z7{=geP7%?zE#n`f7#;5GjHE~9WJ1_;0@Rs|W&WPbfI+Y<6GK|5=#%(K&WK=3#;!|? zY?MiZxN01@%HuFJy z9hstb3R2$Go#5D_5MvtErhWk(?JD6Dh(6ZAGfQOW5v_yE(j%I(ki4IONMo(d82|-< zsDYjn1Q&7@h>hz6>z&(yVv`m%2VQ$$A5Yfj30T!Fwl5vMcPKekt#X<@(dTe4F>hqt z6wznu$wN&={a z-c4U+d0_>91?6?M@it}euJ?Xj%2ze!FM96nvi9p(UK#-Sro1V)mJ>_t#bpo0kL!x- z*6;+1JpoVG1!X6=xO#x)i#@6=`0!%Ex2*zUGBOTt;6@i1_iY6(E-vuix8B{R32?($>7+ zzx*Zk`@LC$0mjzVmp5bsA7MIlSW2r?Ed zodDGaOq|iC=Sl1DR@{_v2040VGRyg*V0UlE<^2o1_3e9j_QitBM>|OE5lhNJplS8Z zG$82MS^!v<_|(Ru49dQe{Vo2xG)vV=(!fyAR8k=faGkx9FinhEfy;Tqg|qcEG_0PM zQ~=afZ5|biiE5&#S|PPU)s=T86abHQ6CN+M+jq{|6qZA+0wPI(7L>3ot1+~R0Xf!M zK_cK809gvzrB-9as|FaWo?r@+vil@i${v`sF_&%x-srJ2tMVTXF)j{o0XsaFYSesSH$1WoHjUCY@f3N~Zpfpj- zK7zAP9`+0N^Ne}7Y#hvhIbK2r_u@6~=)!H|!;hi;p1xUy_24`3us})XK@(A-_@r!jGP7njA0vDH804$ZNcoeL7>gh<2eJ&MJM1HIH zZ8|%NjLC9Yv7ZWPD%iD#!_5Kjyz>a}eDhHPUxV2)m_;=hK3mK0nh2yetezrVp$Uww z&E8X61F5Cm4R%BI=e+ygH*tCI0#_G1TwY$_^6JW?R9(08IkyF33J@%#ny}XdIEU{? zCB{~b%@x35S-=o1tF0|^U@E~QUm2KpJFEXvJ*~Kbw9HW=xu3yQB{Wq;+6-mR@AkFf z$;}>b-@Av&P@Mo7^F?izR_OlaoNS`4Hr(9oQAKf4W|QYk*p&h*z-QOjxGIF-|H1DX zE3SB|dY{`uin=UNwLRp+UwnktR($Kdw{h>@y=1) z{0V;YvtQ!7-+P2V_k-U-TUK1|F7PLR`cwSq$3Mfj-v1{4{9pJU=6S|Pzx)h8{_#(7 zb#;O7eeXLcrC_%!mP(l;1#>|uHkMac7pS%2!=HVWY0)FKx}~0O{V>UCLzx+cop~@0 z*2LIm%@0NHt*3mRv2k1a|h!+MGcUE?*m(R7=qkY`&s+@^nFc zvS7ZqGc8{lRBWD$3aB*jB)IqJJ^aPL`8V*%pZpNIR6PFlGko^x7r4A<48-Dl8brE& zAVYAB0|4Vd!X+r+>q|r}g*Jdv%%QKIN_?JYy#3ZgkH)rjInO&>TwZ}$@zKYh;^U7$ z#r|f+yqhqWf-)5kJ^&uR^#JSPfSdinbb~wqarRG>av)Va`S^4ElmFl!qH67a>p`ys z#*|yY{kI&A5D1emlx<(p-E~-jp}x>s#pP=bN%E$NlnU z`{}m(U()mJZq>}f5P?hao%@m^<>A@)XtzPeZzaD=Z^7n1g?fDERu|qvgnBuCP1N$U)A(u_G1gwu!-RkAAsIF z8w2WWiDMdRVhnPDHqCa1EEr_~&MpSk;l1vM3g3!--=Dj!z@}-wHjztV+Y2Mx;n1f? zpu_V_m)l#m_p=9869fc7voSkN+eW*Ep}<9tGV!JZvQ{4B`k(Kwb2rbzGH zSrT)OXTY?&Z<{+~p2E))B4~RUPXJx$A;(9fl?14opD}`z^K6UYfJw?}F^+rGJp#r1 z42-s$z)#?_8s&xsI$MX6zo)Mi1;CDJ^Ev7Rs%#nQh&?k8B?HZC584(oplPf$_Bl6|3D?&*_~Pj^6lT{w#QUPxt!V_y$9NqBkIxCj zTZH7OSdGIGer4}Y5%$hI+6P{!Gmg^j`1%*!d&}d7dY&yOGVJ*K@ehYE$2r?}!!Z`# zS7rfJD6^jh;-nioTl3xfVS72@^#;VA-;1}OoxA6GgArxi2w!Kp%e&u{FJE3}9=ysp zzs_-d@%!HZ0N<3?SMDkUkID+gF9w?ZpSK0mzTtzL3tR$t`2O4Y`Tc^Q|GiJ~#piqc z!TpEWA8zo+H_z;b8NdSH2mC;|0Z@So+4t&cfX}4meNkZsO01Mn1c6LzwOMB)B{_ux z;l{Np_Sa?{@I`U-2_^HNH0_7d-jS^tFlyQr5MWF))IbyC!4+ek?S(f_8}>It)Yo&$ zN1uFxzx(h0JvT``Etj(}F&C7GxH#5X{6m@uWhT@^9S)bz3mZxW+doi$1^{NU)NM>B zq`!ydfG?hXf!*b7z#IZDE(_M>2G`e5?NNGEy|eW_Eusn*fJ9M<(5R=#Y|vySG6$QP zb1g^2oK`BPbPyP%rh;=Js2WpG^v7!dawADZna2!BlJW z>&uF^HptrSu$lmF4aO|w5nBMD9*rn1nUIuB;jbcCTLVNB#8tqkLJnw9)Yh=B4GhLS zu{k_ksWtX=Hxx)SEoECPmi+=HMO#;_wL)71&l8B*jZ{zfD*~Aa)L`i>mjx0jZ`D|? zm@J)ev|C|@l(atj!G73{7c=GK$XwJIn#{=y1J;NE6k9XEfdLpajd)|;Gsd^p3@ni> zc?p`(1kNY{_b)H8n|1~Wc3qkTmO^mw&Pde5S%@UTfPEgCL$*1%4apn`kOM0vKQ~a2 z1BhVjvIgL=S?cHNeX4^as)|_3Ne3KRv@oSZS7E7P7Eh7${Y-IG14kPx6iK}E${SFCll^w6!Lr~zaWaJYJU z0Imqvf}Tj-V+)#mO~$D~Uy~6OM;hr1%-NS|a}*BY@6LmCZVgVW=z~UsBTLoUa*<4V zOq8sA(gFZz{S=Iwc8y?vy$5l@?qUW+5`5P^yU4?q0KVm3%ml3l%xf8y9~*~&8)d3* zTk9q_mZjP{_RU5_&{kuzYe24Fbw)sGHdlkGv&EWjCJ)+LQP+wp3I>_#)_fha)o(d0 zwvLrNeeC4yV=~Y<&;TBav67UJ;hc;EC6IMfG#yZr0c9?UTn5EH6YX!GEKW~qLunKP270uZn+3y3wDXlqk^{@EV;k8dzP>_Gdr7#m@& zE4VOr_pU%?#l3gmLsQ_hKm8ND{f)Q4g>iYYvy?UHz*U=9l8k==fDX`m1_`J->t=&E zqim!OQWLPr3OMg3Pw8Xw<41q`Q(Rr{Fi$gn{^3U`h4I$g4>3&zmlqS}d55W30L**u ze+$cD!PBSL0F?|v64wPr3EK`0Kl+D%3=pNfb3@5iPcwGVd75zj>;~n*1-|>|Kd|*2 z3jbZB={M#0o@3=W z=^Aa&;git8lPyTYWq`19NqN)s=BPRyA0avb5XX0pR`Va%~C&=`;C~_JDJxLGA2BIKGJ_}@hq}P+gpBY?ta$Fgap)Xdsj9Dr9tG>l{7~=EOP{Cj+<*59-}?SrP#B0z(g1-uV+wVCZ?!}0 zWwHLLjxT+Yt|kE1RWns_9U^(Pd0JU@W3B(84-aMKi*OT)uOEPBt4 zMj~JpfgYTh3BaTQ>WoM_>!$++BbFJ_Q?b+|%i(~-VR2SI0x_d-=~0@hAaEXRt9c$F z&K3x7mw`nUAWM_GRtF6_BM^a6TXTml60jF~aW`Tpnd0m^q#@g!UCsbG;^|_WGb2f+ zj1Z{~0)VIDRR|n(=WJZ9+Vk#TUE;yLd&zDW%an+WwXm7dW6XFC07L5zYE?7jHuT}Z zM1%!!MnQLCTSFZnV?aP@il#6oEC0SpOK_%$Bv3%$;G)6#Y|+Xs!8RcBbdJrO0EJT~ zhJ2lTniCt7Cqy9*piPG??3$@C=E+h^Ud)rReZg2)YinSkWcUhJKcFwAG7+XSVQt3n z7i{XnCi4v(Z0xVB1(gU|0hMZOPYSFJHh!&P6~Q9LkZ8aaMXL&^xU-uft$~@)Dubyc zNRS-V833-r#TY8JgOX@)?yA&`3@u!6xtl5A>?mQ9^G*-~zfO$7znh#iOMUffez_|nq3OoYcycHXV1T!*? z$B}b2fN<$(7hv@$ClK5YUi=%6+q zKe6FTpkj`zG*3Am>Boby)8=ac8ttEf!ln5&s;HzW1(;^GeIr1`3It0sU;sUcy0gpX zqB;OqeNBb~6Qmwp8{gT^4j8zfgit~u5o0oFE^8#@6e*@QK>^g-tY4+2Lr}z+*Nj0m zm|9H_Y!1XGVpLV!+s%0U{uQov7YX)KRjgA1#O_%`#uWr_zQJ2_vA*1ZzPdUfwL#r!7BaszIJ2ntan!W|rMR;+4$%sOiNVg$Dor4@q8?UM zQ3IB>U@J5rw_?S*tXLOM@8`qcX1^tpnz5#hB<3co4*LNckkLuYin&;TIyTnHyeTpA{_)A~MAwffc zQa)!}=sCY^S>WASy?|2L^G#`*M{RPQ(Cx4*oZkH5L) z&DedlrTc7d|Lzr@nhbfGwgcSXm41%Rd&a-FEcU9DzyuxsrzckrPYen;L~y2o4#o9O z)1xCZfcZR?T<@mN^5X``P&*youX&Ii{;&AA4Xi)kk7{TpkSLUjvwHV78)(BXlwRL4 zi2pc6@Ad`Q_@8*=CSYS`GOS+`Mr_Awg$<{nFH zvvbTn8BNsQ5j1?9E?uC5Nn#GVeIK?P^WZh|Ho158q<_^1Mk0em_;}L4#Oa$byQ^1- z;(W;0xrXhOL7WagaeznqlF0pS+ONshS06={1 zFiLhrWT8;Iz%mNK&PCVou+4_}}99zR$V; zI@|5PDLe%!5WAIu-qeA&oh>rYOtsfuKC0~Znt!Xy*8pxZ(KtFb1IX?S zKvVdBHaH|guFd{=XCDlfOyQwLDF`h%vTs-0xki3g5i4bs8yYQZik_QU{UuRP$}tLA zJNdg3m}iv)fb0U0w+{VXN=OI_}Cp$Ei_&hx`KKaXBf#ph41@$+ANf~QZf zF-^tJR{%gL=ePvZWYW|g>q6)i%gNxfG?;OZh0t+{Jwc?$gofye$-I4i@>g4)z%0me2{zK>!c#>byN`0TH-#?HW=?_AE|0|9Re3$_`V;)_>!A07RC zam`--9h>{kY;b2Q^kts=I?D5&_o{vH+gy&v^+ng5`+L0qoE$p7=5?1ZH;1OKsrn~d zP5kr){%0y2Iw)l)_xi_YG{3X*H-x61TV!v_*S@@_A&aQ6$B*}znV}4PakEF63B