This document defines the ARR loading policy for APS (Ardule Pattern Studio). It specifies how a source ARR is applied to the currently edited chain (target), including chain entries, sections, and metadata handling.

• target
  The pattern chain currently being edited in APS.
• source
  The ARR file being loaded.
• ins
  The insertion index in the target chain (cursor position or append point).
• m
  Number of chain entries in the source ARR.
• section
  A metadata range attached to the chain, defined by start–end indices.

1. ARR loading is treated as inserting or appending the source chain into the target chain.
2. The chain itself is a linear time axis without implicit loops.
3. Sections are metadata only and must not break the chain structure.
4. ARR loading should always succeed if possible; conflicts are resolved by renaming and offsetting, not by rejection or silent overwrite.

• Source chain entries are inserted into the target chain while preserving:
  • order
  • repeat counts
  • referenced pattern filenames as-is

APS treats the referenced pattern filename as an opaque identifier during ARR load. In particular, suffix conventions such as:

• _P### (pattern)
• _B### (break)
• _h### (half / 1-bar playback hint; _H is supported for backward compatibility)

MUST be preserved exactly as they appear in the source ARR. ARR loading MUST NOT rewrite these suffixes, normalize them, or edit the referenced ADT files.

Note: Actual 1-bar playback behavior is determined at playback time by the ADT load policy (e.g., PLAY_BARS=1 in the ADT header, with _H### as a fallback hint).

• Insert: at index ins
• Append: at len(target)

Existing sections in the target are processed relative to the insertion point ins.

Condition:

section.end < ins

• No changes are applied.

Condition:

section.start < ins <= section.end

Given an original section:

S = [a .. b]

It is replaced by two sections:

• Left section
  • Name: S_L
  • Range: [a .. ins - 1]
• Right section
  • Name: S_R
  • Range: [ins + m .. b + m]

The original section S is removed.

Condition:

section.start >= ins

• Apply offset +m to both start and end.
• Section name is preserved.

All sections defined in the source ARR are imported into the target.

• Every source section name is prefixed with:

i_

Examples:

• Verse → i_Verse
• Chorus → i_Chorus

This prefix unconditionally marks imported sections.

• Source section ranges are offset by the insertion index ins.

• Semantic name conflicts are not checked.
• If an identical name already exists, a numeric suffix is appended:
  • i_Verse, i_Verse2, i_Verse3, …

This guarantees uniqueness without merging semantics.

• #PLAY in the source ARR is treated as metadata.
• Default behavior:
  • Target playback behavior is not modified.
• Optional behavior:
  • The #PLAY position may be stored with offset applied, as a reference hint.

• Missing pattern files referenced by the source:
  • Loading proceeds.
  • Existing runtime warning mechanisms are used during playback.
• Invalid or out-of-range section definitions:
  • The affected sections are ignored.
  • Loading continues.

ARR loading applies the source chain to the target chain via insertion or append.
Target sections crossing the insertion point are split into _L and _R.
Source sections are imported with an i_ prefix and offset ranges.
Section conflicts are resolved by renaming, not merging.
Pattern filenames (including P/B/H suffixes) are preserved as-is during load.
The chain load operation should succeed whenever possible.

Last updated: 2026-01-03