Functions

## Introduction

This page talks about how to use JavaScript Functions in Perchance to enclose complex calculations in a single call.

## Examples

### The Problem

Let's say you've got a generator where you're rolling some dice and then adding them together, and then selecting a name from a list, and dice sum the if we pick a certain name:

```
dice = {1-6}
name = {Gim|Jin|Sae}

output
  [d = dice.selectOne, n = name.selectOne, ""][if(name == "Sae") {d = d*2, ""} else {""}][name] attacked and dealt [d] damage.

```

Now, that's a fairly simple example (so long as you've read the "if/else Statements" section on this page), but you can see how that one output line could get quite long and messy if you've got slightly more complex requirements. It becomes hard to read and hard to fix when you have bugs. So one way to fix this is to use the special `$output` property that overrides the default output of a list, such that we can spread our code across several lines:

```
output
  $output = [this.joinItems("")]
  [d = dice.selectOne, n = name.selectOne, ""]
  [if(name == "Sae") {d = d*2, ""} else {""}]
  [name] attacked and dealt [d] damage.

```

That's a bit better, but it's still a little hard to read and would be even harder with a "real world" example that is a bit more complex.

### The Solution

So, in these cases, it might be worth encapsulating your code into a function:

```
output
  [n = name.selectOne] attacked and dealt [calculateDamage()] damage.

calculateDamage() =>
  d = dice.selectOne
  if(n == "Sae") {
    d = d*2
  }
  return d

```

With functions we can neatly put each statement on a separate line, but we also don't need to scatter those pesky `, ""` things all around our code, because the only thing that gets output by a function is the thing after the `return` statement (in this case, `d`). In other words, all statements are hidden by default, and a function will output whatever comes after `return`.

Side NoteThe example that I've used so far isn't great, since it would make more sense to implement this sort of thing like this:

```
 dice = {import:dice-plugin}
  character
    Gim
      dmg = [dice("1d6")]
    Jin
      dmg = [dice("1d6")]
    Sae
      dmg = [dice("2d6")]
 output
    [c = character.selectOne, c.getName] attacked and dealt [c.dmg] damage.
    // note: the .getName command gets the "name" of the item that it is applied to

```

But with functions we can do really complex things that would be hard to write and read with most other approaches:

```
calculateDamage() =>
  d = dice.selectOne
  if(n == "Sae") {
    d = d * 2
  } else if(n == "Jin" && d <= 2) {
    d = d + 2
  } else if(n == "Gim") {
    d = d + 1
    if(d == 2) {
      d = d * 4
      n = "Super Saiyan" + n
    }
  }
  return d

```

You can treat the output of a function just like you would the output of any other command/plugin/etc in Perchance, so, for example, we can store the output of `calculateDamage()` and use it later:

```
output
  [n = name.selectOne] attacked and dealt [d = calculateDamage()] damage, which is [d > 5 ? "high" : "low"].

```

### Inputs in Functions

The other cool thing we can do with functions is give them **inputs** which affect their output. Here's an example of a function that accepts a number as an input, and returns that number of animals, all joined together into one bit of text:

```
output
  Here are 3 animals: [getAnimals(3)], and here are 2 more: [getAnimals(2)].

animal = {import:animal}

getAnimals(num) =>
  return animal.selectMany(num).joinItems(" ")

```

And a function can have multiple inputs by separating them with commas:

```
output
  Here are 3 animals joined with hyphens: [getAnimals(3, "-")], and here are 2 more joined with dollar signs: [getAnimals(2, "$")].

animal = {import:animal}

getAnimals(num, joiner) =>
  return animal.selectMany(num).joinItems(joiner)

```

Here's an example generator with that code.

We haven't even scratched the surface of what's possible with functions, but hopefully this is enough to get you started. Feel free to ask questions on the forum!

Note that the Perchance engine is based on JavaScript, so all JavaScript code is valid in Perchance functions (and also in square blocks). This is handy to know because you can search through JavaScript tutorials and cheatsheets if there's not much info on how to do something in Perchance (but always feel free to ask on the Perchance forum).