Tag Semantics

phrack edited this page Jul 24, 2016 · 8 revisions

Tags provide meaning to targets and target regions, which allow ShootOFF to do interesting things when a specific region is shot. You can add as many tags as you'd like to either the target or specific target regions in the Target Editor. Tags can be broadly classified in one of four categories: target tags, target region tags, training exercise tags, and command tags. The latter three categories only apply to target regions.

Target Tags

Target tags provide metadata for the target as a whole that ShootOFF can act on. The following tags have existing meanings to ShootOFF:

  • defaultPerceivedWidth:width in millimeters -- sets default real world width of the target so that it may automatically resized on the projector arena when cameras that work with perspective are in use. (Added in 3.8)
  • defaultPerceivedHeight:height in millimeters -- sets default real world height of the target so that it may automatically resized on the projector arena when cameras that work with perspective are in use. (Added in 3.8)
  • defaultDistance:distance in millimeters -- sets default real world distance from the shooter of the target so that it may automatically resized on the projector arena when cameras that work with perspective are in use. (Added in 3.8)

Target Region Tags

Target region tags always apply as long as the target is on a canvas other than the target editor's canvas. The following tags can be used:

  • name:region_name (e.g. name:pepper_popper) -- gives the region a name that can be used to refer to it in command tags. (Added in 2.0)
  • visible:true or false -- if false, the region is not shown. (Added in 2.0)
  • opacity:percent -- percent is a number between 0 and 1.0 specifying the opacity of the non-image region, where 0 is invisible and 1.0 is fully opaque (default is 0.5 if this tag is not specified). (Added in 3.7)
  • ignoreHit:true or false -- if true, do not factor the region in when determining if a target was hit and do not perform any additional hit processing for the region (default is false). Setting this tag to true effectively means the region only visually exists for the user. (Added in 3.8)

Training Exercise Tags

Training exercise tags are used by training exercises to determine what should happen when a specific region is shot. You can add your own tags when making your own training exercise if you'd like, but you should re-use previously used tags if at all possible to keep tag semantics consistent. The following tags have been used in existing training exercises:

  • points:integer_num_points (e.g. points:5) -- the Shoot for Score training exercise uses this tag to add the specified number of points to your overall score when you shoot a region with a points tag attached to it.
  • subtarget:name (e.g. subtarget:bravo, subtarget:5, etc.) -- the Random Shoot training exercise uses this tag to determine which subtarget you shot. If you miss the region you are supposed to shoot, it repeats for you which subtarget you were supposed to hit.

Training exercise tags are only used if a training exercise is selected. You should test your training exercise to ensure it uses your tags as you intended.

Command Tags

Command tags are in the form command:method_name1(parameter1, ..., parameterN);method_name2(parameter1, ..., parameterN);...method_nameM(parameter1, ..., parameterN) where method_name is a framework method that will be called every single time the region is shot, even if a training exercise is not selected. There can only be one command tag per region, but it may call an arbitrary number of methods. The parenthesis are left off when there are no parameters accepted. The framework currently supports the following command tags:

  • animate and animate(region_name): when no parameter is specified, attempt to run the animation for the tagged region. When a paramater is specified, attempt to run the animation for the region whose name is specified. (Added in 2.0)
  • reset: performs the same operation as clicking the "Reset" button, which deletes all shot markers on the webcam feed and resets whatever training exercise is loaded. (Added in 1.0 -- change from clear_shots to reset in 1.5)
  • play_sound(sound_file): plays sound_file, a .wav file accessible to ShootOFF, over the user's speakers (e.g. play_sound(sounds/metal_clang.wav)). (Added in 1.1) If the sound is a resource in a modular exercise's JAR, you can add an @ to the front of the resources path (e.g. play_sound(@/sounds/hold60.wav)). This assumes the target also belongs to the modular exercise. (Added in 3.8)
  • reverse: tells ShootOFF to play an animation in reverse if the last frame is shown. This is useful for things like pepper popper plates that can swing left or right depending on the side they are currently on. (Added in 2.1)