ACE3/docs/wiki/framework/fastroping-framework.md

---
layout: wiki
title: Fastroping Framework
description: Explains the config values and functions used for making a helicopter fastroping capable.
group: framework
order: 5
parent: wiki
mod: ace
version:
  major: 3
  minor: 5
  patch: 0
---

If you want to prepare a helicopter from your addon for fastroping, there's a few ways to do that.

## 1. Using simple rope origin points

By using simple rope origin points you will only need two config entries:

```cpp
ace_fastroping_enabled = 1;
ace_fastroping_ropeOrigins[] = {
    {x, y, z},
    {x, y, z}
};
```

This will create the ropes at the two given points. If you have defined memory points for the rope origins, you can use them too:

```cpp
ace_fastroping_enabled = 1;
ace_fastroping_ropeOrigins[] = {"ropeOriginLeft", "ropeOriginRight"};
```

You can also use more or less than two rope origins. You can additionally execute code on rope deployment and rope cutting, for example for opening and closing the helicopters doors, see "3. Using onPrepare and onCut functions" for that.

## 2. Using a FRIES

If your helicopter is not fastroping capable by default, you can make it take a FRIES. A FRIES is just a simple model that gets attached to the helicopter with its own rope origin points. ACE3 already includes two FRIES that are used in real life and can be attached to most helicopters.

To make your helicopter FRIES capable, you need to add the following config entries:

```cpp
ace_fastroping_enabled = 2;
ace_fastroping_friesType = "yourFRIESType";
ace_fastroping_friesAttachmentPoint[] = {x, y, z};
ace_fastroping_onCut = "ace_fastroping_fnc_onCutCommon";
ace_fastroping_onPrepare "ace_fastroping_fnc_onPrepareCommon";
ace_fastroping_ropeOrigins[] = {"ropeOriginLeft", "ropeOriginRight"};
```

Let us go through each of them:

- `ace_fastroping_enabled = 2` tells ACE that your helicopter is fastroping capabale but needs a FRIES for that.
- `ace_fastroping_friesType` defines the object that will be used as a FRIES on your helicopter
- `ace_fastroping_friesAttachmentPoint` defines the coordinates at which the FRIES will be attached to.
- See 3.3 for more information about `ace_fastroping_onCut` and `ace_fastroping_onPrepare`. Note: These two entries are necessary for fastroping with a FRIES.
- `ace_fastroping_ropeOrigins` defines the memory points or coordinates from the FRIES where the ropes will be attached to.

## 2.1 Using one of the given FRIES

ACE3 includes two FRIES:

- `ACE_friesAnchorBar`, a system with two extendable rope hooks, based on a system used in the UH60 Blackhawk
- `ACE_friesGantry`, a system consisting of two symmetrical external gantries

Both can be used with 3rd party helicopters. To adjust the width or rotation of the gantries on the second FRIES, you will need to adjust the `initPhase` on the animations. Please look into their current config for further details.

## 2.2 Creating a custom FRIES

To create a custom FRIES you will need to look out for a few things:

- Make sure your FRIES inherits from `ACE_friesBase`.
- If possible, create memory points for the rope origins and name them "ropeOriginLeft" and "ropeOriginRight" for consistency.
- If your FRIES has an animations that should get executed on FRIES preparation and rope cutting, it's recommended to name them "extendHookLeft" and "extendHookRight" so the current `ace_fastroping_fnc_onCutCommon` and `ace_fastroping_fnc_onPrepareCommon` functions can be used.

## 3. Using onPrepare and onCut functions

The `onCut` and `onPrepare` functions are responsible for opening/closing the helicopter doors and animating the FRIES (if equipped) when the FRIES gets prepared and the ropes get cut.

ACE3 provides two functions that are compatible with most helicopters and all ACE3 FRIES. It is recommended to use the naming scheme for doors that is present in the base game so you can use the already existing functions `ace_fastroping_fnc_onCutCommon` and `ace_fastroping_fnc_onPrepareCommon`. You can however define your own functions if you so desire. Note that these functions run in the unscheduled environment, so commands like `sleep` and `waitUntil` will not work unless you use `spawn`. It is recommended to use `ace_common_fnc_waitAndExecute` and `ace_common_fnc_waitUntilAndExecute` instead though.

## 4. Scripting

### 4.1. Add FRIES to helicopter

`ace_fastroping_fnc_equipFRIES`

|    | Arguments | Type | Optional (default value) |
|----| --------- | ---- | ------------------------ |
| 0  | Helicopter | Object | Required |
| **R** | None | None | Return value |

### 4.2. Remove FRIES from helicopter

`ace_fastroping_fnc_unequipFRIES`

|   | Arguments | Type | Optional (default value) |
|----| --------- | ---- | ------------------------ |
| 0  | Helicopter | Object | Required |
| **R** | None | None | Return value |