v50 Steam/Premium information for editors
  • v50 information can now be added to pages in the main namespace. v0.47 information can still be found in the DF2014 namespace. See here for more details on the new versioning policy.
  • Use this page to report any issues related to the migration.
This notice may be cached—the current version can be found here.

Instrument token

From Dwarf Fortress Wiki
Revision as of 08:59, 22 July 2018 by Silverwing235 (talk | contribs)
Jump to navigation Jump to search

Since v0.42.01, instruments are being procedurally generated for each world, but if so desired, it is still possible to define custom instruments in the raws, using an [ITEM_INSTRUMENT] token. Most tool tokens can be used as before, but there are a few instrument-specific tokens, as described in the table below.

The information on this page is sourced from the file raw/objects/examples and notes/item_instrument_example.txt, which also includes useful example instrument definitions.

Token Arguments Description
PLACED_AS_BUILDING Makes the instrument stationary.
DOMINANT_MATERIAL_PIECE
  • instrument piece
Sets a piece as the central part of the instrument.
INSTRUMENT_PIECE
  • token
  • tool token
  • singular
  • plural
  • STANDARD/ALWAYS_PLURAL/ALWAYS_SINGULAR
Defines an instrument piece. token is the identifier that can be used in other raw tags to refer to this instrument piece. tool token is the tool which is required (and consumed) during the construction process to create this instrument piece.

If an instrument does not have any pieces, SELF can be used for any argument which needs to be an instrument piece.

VOLUME_mB
  • min
  • max
The instrument's volume range, in millibels (100 mB = 1 dB).
SOUND_PRODUCTION * various tokens Defines how a musician can produce sound when using this instrument. Can be used multiple times. Valid tokens and their required additional arguments are:
  • PLUCKED_BY_BP, PLUCKED (requires two tokens, actor then target)
  • BOWED (two tokens)
  • STRUCK_BY_BP, STRUCK (two tokens)
  • VIBRATE_BP_AGAINST_OPENING
  • BLOW_AGAINST_FIPPLE, BLOW_OVER_OPENING_SIDE, BLOW_OVER_OPENING_END, BLOW_OVER_SINGLE_REED, BLOW_OVER_DOUBLE_REED, BLOW_OVER_FREE_REED
  • STRUCK_TOGETHER, SHAKEN
  • SCRAPED (two tokens), FRICTION (two tokens)
  • RESONATOR
  • BAG_OVER_REED (two tokens), AIR_OVER_REED (two tokens), AIR_OVER_FREE_REED (two tokens), AIR_AGAINST_FIPPLE (two tokens)
PITCH_CHOICE
  • method
Defines how the pitch can be varied by the musician. Can be used multiple times. Valid methods are:
  • MEMBRANE_POSITION
  • SUBPART_CHOICE
  • KEYBOARD
  • STOPPING_FRET (requires two tokens, first for "string" second for "neck" -- or whatever is being pressed against what), STOPPING_AGAINST_BODY (two tokens), STOPPING_HOLE, STOPPING_HOLE_KEY
  • SLIDE
  • HARMONIC_SERIES
  • VALVE_ROUTES_AIR
  • BP_IN_BELL
  • FOOT_PEDALS (two token, first is what is being changed e.g. "strings", second is "body" which has pedalboard -- or whatever piece is being stepped on)
TUNING
  • method
  • instrument piece
Can be used multiple times. Valid methods are: PEGS, ADJUSTABLE_BRIDGES, CROOKS, TIGHTENING, LEVERS.
PITCH_RANGE
  • min pitch
  • max pitch
From the example file:

Pitch is <min>:<max> in cents with middle C at zero. There are 1200 cents in an octave. The game verbally differentiates values from -4200 to 4200, but you can go outside that if you like. The in-game generated instruments will range from roughly C0 to C8 (-4800 to 4800), sometimes beyond for really unusual ones.

You can also use INDEFINITE_PITCH.

TIMBRE
  • any number of timbre words
Valid timbre words are: CLEAR, NOISY, FULL, THIN, ROUND, SHARP, SMOOTH, CHOPPY, STEADY, EVOLVING, STRONG, DELICATE, BRIGHT, GRACEFUL, SPARSE, BREATHY, STRAINED, BROAD, LIGHT, MELLOW, WOBBLING, FOCUSED, EVEN, FLUID, VIBRATING, QUAVERING, EERIE, FRAGILE, BRITTLE, PURE, PIERCING, STRIDENT, WAVERING, HARSH, REEDY, NASAL, BUZZY, ROUGH, WARM, RUGGED, HEAVY, FLAT, DARK, CRISP, SONOROUS, WATERY, GENTLE, SLICING, LIQUID, RAUCOUS, BREEZY, RASPY, WISPY, SHRILL, MUDDY, RICH, DULL, FLOATING, RINGING, RESONANT, SWEET, RIPPLING, SPARKLING.
REGISTER
  • min pitch
  • max pitch
  • any number of timbre words
See PITCH_RANGE and TIMBRE for possible values. The pitch range overrides the global pitch for a register, but the register timbres are added to the global ones.
MUSIC_SKILL
  • skill token
The skill should be one of the music-related skill tokens.