Skip to content

Latest commit

 

History

History
434 lines (421 loc) · 26.3 KB

CUSTOM.md

File metadata and controls

434 lines (421 loc) · 26.3 KB
Raw

Editors

  • There are currently 3 editors: Spirit, Power, and Blight
  • They are found on right side of mod by click the "Show Editors" button
  • Make sure you have selected a player color first

Spirits

In place of following these instructions you can instead use https://spiritislandbuilder.com/ and hit the "Export TTS file" button

  • https://kb.tabletopsimulator.com/custom-content/custom-tile/
  • Set name of object to that of spirit
  • Place object onto spirit editor and click "Make Me A Spirit!" button
    • This will add the "Spirit" tag as well as basic scripting
    • The "Choose Spirit" button should now appear on the backside of the panel
      • Note: You may have inverted the top and bottom images
  • Add tag to object for spirit's complexity, one of the following:
  • Add tag to object for additional rules spirit uses, this will make sure the content can't be used without the required rules:
  • Add snap points to presence track(s) where presence should be setup
  • Presence track fixed (non choice) elements:
    • Set the state to match the element
    • If multiple elements appear on same spot simply stack elements on top of each other
    • Once all elements are set press the "Update Elements" button
  • Presence track energy:
    • For each time that energy gain increases grab energy tokens from bag and stack them onto spot
    • Energy tokens have a 2nd state to be used for bonus energy (e.g. Finder)
    • Once all energy is set press the "Update Energy" button
    • Note: You don't need to put them on every spot, only when income increases
    • Note: Don't forget about starting spot if it's not zero
  • Innate thresholds:
    • Grab a threshold token (X) and place it onto object where you want the threshold decal to appear
    • Then grab elements from the element bag right next to threshold
    • Set the state to match the element
    • Stack elements on top of the threshold token (X)
    • Once all thresholds are set press the "Update Threshold" button (the top one)
    • Note: for thresholds with OR (e.g. Trickster), you'll need to manually edit the json file to add a second threshold at the exact same coordinates as the other one
  • Spirit marker & reminder token (optional):
    • Grab a reminder token from the editor and place it on the spirit panel (or press "Populate Reminder")
    • Position and scale it to show the best image of the spirit's face
    • Flip the panel over if the other side offers a better image
    • Press the "Update Reminder" button

Power Cards

  • https://kb.tabletopsimulator.com/custom-content/custom-deck/
    • The card/deck image should be in portrait orientation
  • Set name of object to that of power card
  • Move card onto power card editor
  • Change values that appear to match card
  • Thresholds:
    • Grab a threshold token (X) and place it onto object where you want the threshold decal to appear
    • Then grab elements from the element bag right next to threshold
    • Set the state to match the element
    • Stack elements on top of the threshold token (X)
    • Once all thresholds are set press the "Update Threshold" button (the bottom one)
    • Note: for thresholds with OR (e.g. Trickster), you'll need to manually edit the json file to add a second threshold at the exact same coordinates as the other one
    • Note: the decal will appear smaller than the actual size of the object, just a TTS limitation for how small an object can be
  • Reminder token (optional):
    • Grab a reminder token from the editor and place it on the cart art (or press "Populate Reminder")
    • Position and scale it to show the best image
    • Press the "Update Reminder" button

Aspects

Progression Cards

progressionDeck = {
    -- reverse order
    {"<power card guid>", true|false (whether this is major power or not)},
    {"<power card guid>", true|false (whether this is major power or not)},
    {"<power card guid>", true|false (whether this is major power or not)},
    ... (add additional lines as needed)
}

Blight Cards

Fear Cards

Expansions

Adversary & Scenario

Advanced

This section is meant for users who are familiar with both the tts mod and programming. It may be helpful to look at an adversary or scenario that already does something to similar to get a feel for how to code the feature you're looking for.

Spirit

  • broadcast: string - text to display when selecting spirit
    • Note: this needs to be set manually in json under LuaScriptState for spirit, anything set in LuaScript will be lost to spirit updater operation

Aspect

  • broadcast: string - text to display when selecting aspect
    • Note: unlike the spirit broadcast, this can be set in the script

Adversary & Scenario

  • collision workaround
    • workaround for TTS bug https://tabletopsimulator.nolt.io/770
    • onObjectCollision: boolean - set to true if you have custom object collision code
    • onObjectCollisionEnter(params)
      • params: table - contains parameters for callback
        • hit_object: object - object registered to receive collision events
        • collision_info: table - table containing data about collision
    • onObjectCollisionExit(params)
      • params: table - contains parameters for callback
        • hit_object: object - object registered to receive collision events
        • collision_info: table - table containing data about collision
  • customLoss: boolean - set to true if adversary/scenario has non scriptable loss condition
  • Setup Callbacks:
    • requirements - determine whether random adversary/scenario should be used with current setup
      • requirements: boolean - set to true if you have Requirements function
      • Requirements(params)
        • params: table - contains data about game setup
          • eventDeck: boolean - whether event deck is being used
          • blightCard: boolean - whether blight card is being used
          • expansions: table - expansions included in setup, keys are the name of them
          • thematic: boolean - whether thematic island setup is enabled
          • adversary: boolean - whether an adversary is being used (only exists for Scenario call)
        • return boolean - whether this adversary/scenario should be used
    • invaderDeckSetup - allows you to modify invader deck
      • invaderDeckSetup: boolean - set to true if you have InvaderDeckSetup function
      • InvaderDeckSetup(params)
        • params: table - contains data about game setup
          • level: number - level of current adversary (only exists for Adversary call)
          • deck: table - table containing current setup for invader deck
            • 1, 2, 3: indicates random card of that stage
            • W, M, J, S: indicates specific stage I card
            • We, Me, Je, Se, C: indicates specific stage II card
            • MW, JW, SW, MJ, SM, JS: indicates specific stage III card
            • 3*: will have UI treat card as stage III card as stage II (e.g. Prussia 2)
            • blacklist: table - table containing cards to not appear randomly in invader deck
              • Any specific cards used in the invader deck have implied blacklist (e.g. Scotland 2)
              • Use a specific card name per above and set to true in the table
          • return table - updated table for invader deck setup
    • mapSetup - allows you to modify the pieces on a board
      • mapSetup: boolean - set to true if you have MapSetup function
      • MapSetup(params)
        • params: table - contains data about game setup
          • level: number - level of current adversary (only exists for Adversary call)
          • name: string - name of the board being setup
          • pieces: table - 2D, contain keys for each land number, and each land table has values for piece name
          • original: table - same format as pieces, but is the setup symbols printed on the island board (e.g. Habsburg 2)
          • extra: boolean - whether the current board is the extra board from setup variant
        • return table - updated table for pieces setup
    • postSetup - called after all other setup steps have completed
      • postSetup: boolean - set to true if you have PostSetup function
      • postSetupComplete: boolean - set to true at end PostSetup function
      • PostSetup(params)
        • params: table - contains data about game setup (only exists for Adversary call)
          • level: number - level of current adversary
          • other: table - contains data about other adversary
            • exist: boolean - whether there is a second adversary
            • level: number - other adversary level
    • broadcast
      • hasBroadcast: boolean - set to true if you have a Broadcast function
      • Broadcast(params)
        • params: table - contains data about adversaries (only exists for Adversary call)
          • level: number - level of current adversary
          • other: table - contains data about other adversary
            • exist: boolean - whether there is a second adversary
            • level: number - other adversary level
        • return string - what players should be told, nil otherwise
    • automatedVictoryDefeat - allows you to start timers that will check for win/loss conditions -automatedVictoryDefeat: boolean - set to true if you have AutomatedVictoryDefeat function -AutomatedVictoryDefeat()
  • Adversary Specific:
    • Note: notebook contains sample code for adversary
    • fearTokens: table - contain keys 0->6 representing the fear token modifier for each adversary level (e.g. England 6)
    • setupBlightTokens: table - contain keys 0->6 representing the starting blight token per board modifier for each adversary level
    • reminderSetup
      • reminderSetup: boolean - set to true if you have ReminderSetup function
      • ReminderSetup(params)
        • params: table - contains data about game setup
          • level: number - level of current adversary
        • return table
          • ravage: object - ravage reminder object, use "Generic" if you don't have a custom one
          • afterRavage: object - after ravage reminder object, use "Generic" if you don't have a custom one
          • build: object - build reminder object, use "Generic" if you don't have a custom one
          • afterBuild: object - after build reminder object, use "Generic" if you don't have a custom one
          • explore: object - explore reminder object, use "Generic" if you don't have a custom one
          • afterExplore: object - after explore reminder object, use "Generic" if you don't have a custom one
    • adversaryUI
      • hasUI: boolean - set to true if you have AdversaryUI function
      • AdversaryUI(params)
        • params: table - contains data about game setup
          • level: number - level of current adversary
          • supporting: boolean - whether this is supporting adversary or not
        • return table - note setup adversary effects can be excluded from UI
          • loss
            • tooltip: string - text of adversary loss condition, use \n to add line breaks
            • counter
              • text: string - text that should appear before counter
              • buttons: boolean - whether buttons should appear for counter (e.g. Habsburg)
              • callback: function - name of callback to occur after loss counter buttons are pressed (only called when buttons is true)
          • escalation
            • tooltip: string - text of adversary escalation, use \n to add line breaks
            • random: boolean - whether random terrain button needs to appear for adversary (only exists for secondary adversary) (e.g. Sweden)
          • one DEPRECATED
            • name: string - name of adversary effect
            • tooltip: string - text of adversary effect, use \n to add line breaks
          • two DEPRECATED
            • name: string - name of adversary effect
            • tooltip: string - text of adversary effect, use \n to add line breaks
          • three DEPRECATED
            • name: string - name of adversary effect
            • tooltip: string - text of adversary effect, use \n to add line breaks
          • four DEPRECATED
            • name: string - name of adversary effect
            • tooltip: string - text of adversary effect, use \n to add line breaks
          • five DEPRECATED
            • name: string - name of adversary effect
            • tooltip: string - text of adversary effect, use \n to add line breaks
          • six DEPRECATED
            • name: string - name of adversary effect
            • tooltip: string - text of adversary effect, use \n to add line breaks
          • effects table - contains data for all adversary effects
            • [level] table - level of adversary effect
              • name: string - name of adversary effect
              • tooltip: string - text of adversary effect, use \n to add line breaks
              • ravage: boolean - reminder that adversary has effect that triggers during ravage actions
              • afterRavage: boolean - reminder that adversary has effect that triggers after ravage step
              • build: boolean - reminder that adversary has effect that triggers during build actions
              • afterBuild: boolean - reminder that adversary has effect that triggers after build step
              • explore: boolean - reminder that adversary has effect that triggers during explore actions
              • afterExplore: boolean - reminder that adversary has effect that triggers after explore step
          • invader DEPRECATED
            • ravage: boolean - reminder that adversary has effect that triggers during this invader step
            • build: boolean - reminder that adversary has effect that triggers during this invader step
            • explore: boolean - reminder that adversary has effect that triggers during this invader step
        • [loss callback function](params)
          • params: table - contains data about update
            • count: number - new count for loss counter
        • UpdateAdversaryLossCounter(params) - when adversary doesn't use buttons you can call this function to update text (e.g. Russia)
          • params: table - contains data about update
            • support: boolean - whether this is supporting adversary or not
            • count: number - new count for loss counter
    • invaderSetup - called before all other setup steps have started
      • invaderSetup: boolean - set to true if you have InvaderSetup function
      • InvaderSetup(params)
        • params: table - contains data about game setup
          • level: number - level of current adversary
        • return table - modifications to be made to invader pieces
          • explorer
            • tooltip: string - text to appear when hovering over invader piece
            • color: string - RRGGBB hex code for the color that appears on every state
            • states: table - contains data about new states for piece
              • [index]: table - contains data for specific new state
                • color: string - RRGGBB hex code for the color that appears on this state
                • copy: integer - state id for which to copy the transform data from
          • town
            • tooltip: string - text to appear when hovering over invader piece
            • color: string - RRGGBB hex code for the color that appears on every state
            • states: table - contains data about new states for piece
              • [index]: table - contains data for specific new state
                • color: string - RRGGBB hex code for the color that appears on this state
                • copy: integer - state id for which to copy the transform data from
          • city
            • tooltip: string - text to appear when hovering over invader piece
            • color: string - RRGGBB hex code for the color that appears on every state
            • states: table - contains data about new states for piece
              • [index]: table - contains data for specific new state
                • color: string - RRGGBB hex code for the color that appears on this state
                • copy: integer - state id for which to copy the transform data from
    • limitSetup - called before board setup starts in case any pieces need to be limited (e.g. France)
      • limitSetup: boolean - set to true if you have LimitSetup function
      • limitSetupComplete: boolean - set to true at end LimitSetup function
      • LimitSetup(params)
        • params: table - contains data about game setup
          • level: number - level of current adversary
          • other: table - contains data about other adversary
            • exist: boolean - whether there is a second adversary
            • level: number - other adversary level
    • preSetup - called before all other setup steps have started DEPRECATED
      • preSetup: boolean - set to true if you have PreSetup function
      • preSetupComplete: boolean - set to true at end PreSetup function
      • PreSetup(params)
        • params: table - contains data about game setup
          • level: number - level of current adversary
  • Scenario Specific:
    • fearCards: table - contains keys 1->3 representing the change of fear cards in each part of the deck
    • setupBlightTokens: number - modifies amount of starting blight per board (e.g. Blitz)
    • blightTokens: number - modifies amount of flipped card blight per board (e.g. Blitz)
    • customVictory: boolean - set to true if scenario has non scriptable victory condition
    • preSetup - called before all other setup steps have started
      • preSetup: boolean - set to true if you have PreSetup function
      • preSetupComplete: boolean - set to true at end PreSetup function
      • PreSetup(params)
        • params: table - currently nil
    • boardSetup - allows you to override the current board layout (e.g. Great River)
      • boardSetup: boolean - set to true if you have BoardSetup function
      • BoardSetup(params)
        • params: table - contains data about game setup
          • boards: number - number of boards to be setup
        • return table - new board layout

Other

  • Trigger to run when game starts:
    • Create object and place on top of spirit panel
    • Tag object with "Setup"
    • spiritName: string - name of the spirit setup is associated with
    • doSetup(params)
      • params: table - contains data about player
        • color: string - is the color of the player who picked the spirit
        • spiritPanel: object reference - the spirit panel object for the spirit that the setup object belongs to
      • return bool - was setup successful?
  • Trigger to run during time passes:
    • Create object and tag with "Time Passes"
    • timePasses()
  • Trigger to run during phase changes:
    • Create object and tag with "Phases"
    • changePhase(params)
      • params: table - contains data about phase transition
        • phase: number - is the new phase just changed to
          • 1: Spirit Phase
          • 2: Fast Phase
          • 3: Invader Phase
          • 4: Slow Phase
          • 5: Time Passes
        • turn: number - is the current turn number
  • Trigger to modify the cost of played cards
    • Create object and tag with "Modify Cost"
    • modifyCost(params)
      • params: table - contains data about the player and the cards played
        • color: string - is the color of the player whose card cost is being calculated
        • costs: table - maps card GUIDs (as keys) to costs (as values)
      • return table - the costs table, modified appropriately
        • e.g. Blitz would reduce the cost of all fast cards by 1, cards could be ignored in cost calculations by deleting them from the table
  • Trigger to modify the energy gained with the "Gain" button
    • Create object and tag with "Modify Gain"
    • modifyGain(params)
      • params: table - contains data about the energy gain
        • color: string - is the color of the player who is gaining energy
        • amount: number - baseline amount of energy to gain (before bargain deductions)
      • return number - modified amount of energy to gain (before bargain deductions)
  • Trigger to run when a player successfully gains/pays energy (or successfully undoes these operations)
    • Create object and tag with "Gain Pay"
    • onGainPay(params)
      • params: table - contains data about gain/pay operation
        • color: string - is the color of the player who gained/paid energy
        • isGain: bool - true if the operation is a gain, false if it's a pay
        • isUndo: bool - true if the operation is being undone (right click), false otherwise
        • amount: number - amount of energy gained/paid (before bargain deductions); positive for gain or pay
  • Trigger to modify the number of cards gained
    • Create object and tag with "Modify Card Gain"
    • modifyCardGain(params)
      • params: table - contains data about the player and the cards played
        • color: string - is the color of the player whose card cost is being calculated
        • major: boolean - true if gaining majors, false if gaining minors
        • count: number - the number of cards being gained
      • return number - the number of cards to gain
  • Trigger to modify how a spirit's elements are counted
    • Create object and tag with "Modify Elements"
    • modifyElements(params)
      • params: table - contains data about the player and their elements
        • color: string - is the color of the player whose elements are being counted
        • elements: table - a table of eight numbers, representing the number of each element in order, indexed by numbers 1-8 (1: Sun, 2: Moon, 3: Fire, 4: Air, 5: Water, 6: Earth, 7: Plant, 8: Animal)
      • return table - the elements table, modified appropriately
  • Trigger to modify a elemental thresholds
    • Create object and tag with "Modify Thresholds"
    • modifyThresholds(params)
      • params: table - contains data about the threshold
        • color: string - is the color of the player for whom the threshold is being evaluated
        • object: object reference - the object on which the threshold sits (e.g. spirit panel, aspect card, power card)
        • elements: table - a table of eight numbers, representing the number of each element in order, indexed by numbers 1-8 (1: Sun, 2: Moon, 3: Fire, 4: Air, 5: Water, 6: Earth, 7: Plant, 8: Animal)
      • return table - the elements table, modified appropriately