Playbooks

A playbook is a named group of scripts and the manager that says which of them are on: strategies (.tzs), risk scripts (.tzr), a portfolio controller (.tzp), and one manager (.tzm). You leave the manager running; when the market is in the situation it was written to recognise, it turns strategies on and off and changes the risk script, in a backtest and live alike.

The manager#

A manager is a pure calculation (see Script kinds and the contract in the host API, §5.20). When a candle of the playbook's timeframe closes it is given the closed candles up to that one, the price, the decision it gave last time and the names of the members, and it answers with the complete set that should be on. It reads the market only -- not the account and not a member's profit -- so the same script gives the same decisions live and in a backtest. Two examples ship: 74_trend_filter.tzm and 75_session_hours.tzm.

What the terminal does with an answer#

The rules are the host's, the same in both places:

• Never on a tick. A decision is made when a candle of the playbook's timeframe closes (1m, 5m, 15m, 30m, 1h, 4h, 1D, UTC-aligned like the exchange's). The price it is given is that candle's close.
• No look-ahead. A decision takes effect from the next event, never on the one that closed the candle.
• A decision that names what is not a member is refused whole. active names strategies of the playbook, risk a risk script of it, portfolio a portfolio controller of it. A refused decision, or a script that fails, changes nothing and is counted; three in a row apply the playbook's fault policy: all_off (the default: every strategy is suspended and the account's own risk is left in force) or hold.
• confirm_bars. A change is made only when that many evaluations in a row asked for the same thing (1 is at once), so one odd candle does not flip a strategy.
• A flap guard. Past six changes in an hour the last state is held, and the host says so once; the manager is still asked at every candle.
• A hole in the candles (a minute missing from the series) makes the manager start again: no previous, only the candles since. What is on stays on until it decides again.
• Suspending a strategy means no new entries. What happens to its orders and positions, and to the strategy that takes over, is the playbook's hand-over choices (below).

Live#

A playbook is started from the Playbooks window on an account (demo, replay, or real), and it never starts by itself after a restart (the window offers what was running). Its candles are read from the backend every 20 seconds. On start the manager is replayed over the last 500 candles, one at a time, so the state it begins in is the one it would have reached had it been running -- the same function over the same candles a backtest uses; what happened while replaying is not announced. Then, at every candle that closes:

• A strategy the manager does not name is turned off: it opens nothing, the entries it had resting are withdrawn, and what it holds keeps its stop and its target (or is closed, with when_off: "flatten"). It is a hold of its own: the feed coming back does not lift it, and lifting it does not defeat a stale feed. A strategy is the member whose file it was started from.
• The risk script (and portfolio controller) the manager names is put in force on the account, the same bind as "Activate now" in the Risk window but written to no file: the bindings file and its history are left as they are. Every change is in the risk journal, as the operator Playbook <name>. When the manager names none, or the playbook stops, the account's own binding is read again from the file and put back.
• The event playbook_changed is told to the hooks (playbook, state, from_state, why, on, off, risk, portfolio, cause), so a webhook can say who is on without a script. A hook can be for one playbook by name.
• A playbook only starts if every script is pinned and unchanged; it only starts on the real account if its file says allow_real. Up to four run at once.

In the terminal#

• The Playbooks window (command palette: Open Playbooks). The playbooks on the left; the one open on the right as cards: What it watches (the instrument -- empty is the market in hand -- the timeframe, and how many candles in a row must agree before it acts), Manager (the .tzm, its configuration, and Test now, which runs it on the candles of now and says what it would decide and how many times it changed over them, switching nothing), Members (add a strategy, a risk script or a portfolio controller from the script browser, filtered to what each slot takes; what is on before the first decision), When it changes hands (the choices below, each with a line that says what it will do), Safety (the fault policy, close_on_stop, allow_real) and, while it runs, Running: the situation, since when and why, who is on and who is off, the risk script in force, anything waiting to take over, and the last changes. Pin all and save pins every script to what is on disk; Start is disabled, with the reason beside it, until the playbook is saved and every script is pinned. A strategy is found by the file it was started from: start it as usual (Running Scripts, or Start the missing strategies, which opens the usual form for each) and the playbook switches it.
• Starting on the real account asks first, listing what the playbook will move, and needs allow_real in the playbook.
• Backtests. The Playbook card, beside Risk: choose a playbook and each strategy ticked that is one of its members runs under its manager (a strategy that is not a member runs as it is, and is said). A playbook that swaps risk scripts needs A script under Risk: that is what each run starts under and comes back to when the manager names none. Under a finished run: the strip of the situations over the run, and for each situation how long it lasted, how long the strategy could enter, and what the trades that began in it made -- so a manager is judged by what its situations were worth, not only by the total. A playbook runs one instrument at a time (not Together) and not in a sweep.
• On the chart. The situations of a running playbook are tinted behind the price, named in the corner of each, and the line the manager draws is drawn on the charts of its instrument and timeframe. Neither is a drawing: they cannot be selected, and they go when the playbook stops. Show its situations on the charts turns them off for one playbook.

examples/playbooks/trend-gate.json is a playbook around 74_trend_filter.tzm: the trend follower is on in a trend, the fader in a range, and a tighter risk script is in force in the range. Copy the scripts it names into the scripts folder, open it in the Playbooks window and press Pin all and save.

Changing hands#

What should happen when the manager turns a strategy off while it has orders working or a position open, or turns another on before the first is done? The playbook says, in hand_over; the defaults are the cautious ones (nothing is closed that the strategy itself would close, and nothing rests that it was told to stand aside from).

Choice	Values	What it does
positions	keep (default), close_now, close_after	A strategy that is turned off keeps what it holds, managed to its own end (its stop and target stay, and it may still exit); or it is closed at market the moment it is turned off; or it is kept for close_after_minutes and closed then if the strategy is still off.
resting_orders	withdraw (default), keep	The entry orders it has resting are withdrawn (left there they could fill after it was told to stand aside), or kept. Its stops and targets are never touched: they are exits.
wait_for_flat	false (default), true	A strategy the manager turns on waits until the ones it turned off hold nothing and have nothing working. Two strategies never hold at once through a change. With wait_max_minutes it waits no longer than that (0 is as long as it takes), and on_wait_timeout says what then: proceed (turn it on anyway) or close_them (close what the others still hold, and turn it on).
on_risk_change	keep_orders (default), withdraw_entries	When the risk script in force changes, the entries resting were judged by the policy that has gone: they stay for the new one to judge what comes after, or they are withdrawn.
close_on_stop	false (default), true	Stopping the playbook closes what its strategies hold.

In a backtest, positions, resting_orders and on_risk_change act exactly as they do live. wait_for_flat does not: the strategies of a backtest are separate runs on separate accounts, so each is switched on as soon as the manager names it, and the result says that the choice was not simulated.

The file#

~/.config/ttt/t0/playbooks/<name>.json, at most 16, each at most 256 KiB. Unknown fields are refused, so a typo is not silently dropped.

{
  "format": "ttt-playbook/1",
  "name": "trend-gate",
  "symbol": "BTCUSDT",
  "timeframe": "1h",
  "manager": { "path": "managers/trend_filter.tzm", "sha256": "…", "config": { "fast": 8, "slow": 24, "enter": 0.02, "leave": 0.01, "trend": ["follow"], "range": ["fade"], "trend_risk": "wide", "range_risk": "" } },
  "members": [
    { "name": "follow", "kind": "strategy", "path": "strategies/follow.tzs", "sha256": "…" },
    { "name": "fade",   "kind": "strategy", "path": "strategies/fade.tzs",   "sha256": "…" },
    { "name": "wide",   "kind": "risk",     "path": "risk/wide.tzr",         "sha256": "…", "config": { "risk_per_trade": "0.01" } }
  ],
  "initial": { "active": [], "risk": null, "portfolio": null },
  "on_fault": "all_off",
  "hand_over": { "positions": "keep", "resting_orders": "withdraw", "wait_for_flat": false, "on_risk_change": "keep_orders" },
  "confirm_bars": 1,
  "close_on_stop": false,
  "allow_real": false
}

Paths are absolute or relative to the scripts folder. The sha256 pins are taken when the playbook is saved; a script that has changed since it was pinned does not start live until it is pinned again, by a person. A member's file must be of its kind (.tzs/.tz for a strategy, .tzr/.tz for a risk script, .tzp/.tz for a portfolio controller) and the manager .tzm. initial is what is on before the first decision. Member and playbook names are lowercase letters, digits, - and _.