box.lic

=begin
  Various utilities for handling lockpicking, disarming and boxes -- for those who don't want to fully automate but
	would still like some convenience functions.  Also has some utility for those getting boxes picked.

  Usage:
   ;box HELP                Shows this help text.

   ;box EMPTY [<container>] Open the currently held box, gather the coins, and empty it into the specified
                            container (or your default lootsack)
   ;box GRAB [<container>]  Attempts to grab a closed (and presumably locked) box from the specified
                            inventory container(s), or any inventory container if none are specified.
                            Separate multiple container names with commas or semicolons.
   ;box LIST [<container>]  List known boxes in the specifed containers(s), or all containers if no
                            container is specified.

   ;box STATUS              Shows your current lootsack and most recent customer.

   ;box LOOTSACK [<cont>]   Sets/shows your current lootsack.  Note that this affects ALL Lich scripts.

   ;box SCAN                LOOKs in all of your containers to attempt to force inventory information
                            to refresh.  Use this if GRAB or LIST are acting up.  Will not examine
                            closed containers, or containers that are in other containers.

   ;box ACCEPT [WAIT]       ACCEPT an offer and remember who offered it.  If 'WAIT' is specified, will
                            wait for an offer if one is not currently pending.  Items that do not look
                            like boxes will not be automatically accepted.
                            Puts ;box in 'customer mode'

   ;box JOB                 Ask the box pool worker for a job.
                            Puts ;box in 'job mode'

   ;box RETURN [<player>]   Customer mode: Return the box you recently accepted to whoever offered it to you,
                            or to <player>.
                            Job mode: Asks the worker to check your work.

   ;box NEXT [<player>]     Customer mode: Does ';box RETURN <player>' and ';box ACCEPT wait', in
                            that order.
                            Job mode: Does ';box RETURN' and ';box JOB', in that order.

   ;box DISARM or DETECT    Disarm the currently held box, whatever it happens to be named -- or detect
                            traps without attempting to disarm.

   ;box SCARABS [<opts>]    Configures the automatic scarab disarming that can happen as part of ;box disarm
                            Type `;box SCARABS` by itself for more details.

   ;box UNLOCK [<lockpick>] Unlock the currently held box using the specified lockpick.  If <lockpick>
                            consists of multiple words, this will try to find any matching lockpick,
                            even if the adjectives do not match the game's adjectives.  For instance,
                            ';box vaalin lockpick' will 'a/dark vaalin/lockpick', even though you
                            would normally need to type 'get my dark lockpick'
                            If no lockpick is specified, whatever item you are holding (other than the
                            box) is assumed to be the lockpick you want to use.

   ;box COMMAND             Shows or changes the current command used to pick boxes.  Useful for using
                            lock mastery.  Type ;box COMMAND by itself to see more details on this
                            option.

   ;box WINDOW [<option>]   Configures the lockpicking results window, where <option> is one of:
                            OFF, ON, SAVE, CLEAR, or SHOW.  WINDOW by itself will show the current
                            configuration.  Only available in StormFront.  EXPERIMENTAL.

  This script is oblivious to items that are in closed containers.

	  author: LostRanger (thisgenericname@gmail.com)
	  game: GemStone
	  tags: lockpicking
	  required: Lich >= 4.6.0.

  version: 0.17 (2020-03-06)

  changelog:
    version 0.17 (2020-03-06)
      * Should no longer stall on open rolls.

    version 0.16 (2020-03-03)
      * Disarm/detect captures should no longer be confused by something else referencing the box, such as a LOOK ON TABLE in-flight.
      * Disarm/detect messaging no longer stalls ;box if the box is already open.
      * NPC dialog when acquiring a job with ;box job is now copied to the lockpicking window
      * Who you accepted a box from using ;box accept is now copied to the lockpicking window.

    version 0.15 (2020-03-02)
      * ;box should properly work again when there is no lockpicking window.

    version 0.14 (2020-03-02)
      * Calipers can now be calibrated with no box target.  This will fail if you don't have at least 40 ranks of LM.
      * Fix a hang when attempting to calibrate already-calibrated calipers.
      * Fix a bug when looking for a box on a nonexistant table.
      * `;box empty` and `;box drop will` properly fail out if you aren't holding a box but have one from the pool.
      * Added an option to automatically disarm and optionally pick up or loot scarabs, configurable via `;box scarabs`
        NOTE: AUTOMATIC LOOTING IS EXPERIMENTAL.  IT MAY KILL YOU (but shouldn't.)

    version 0.13 (2020-03-01)
      * ;box now remembers whether it's working with traditional customer boxes or boxes from the job pool.
        `;box job` asks the worker for a job and puts ;box in 'job mode'
        `;box accept` puts ;box back in 'customer mode'
        `;box next` and `;box return` now interact with the box pool while in job mode:
           ;box return does ASK <npc> ABOUT CHECK, and ;box next follows that up with ASK <npc> ABOUT JOB.

    version 0.12 (2020-03-01)
      * Added preliminary support for the box pool.  To work, you *may* occasionally need to manually LOOK ON TABLE.
        Improved support to come in a later release.

    version 0.11 (2019-07-11)
      * Fix accidental garbage that breaks the script in Ruby 2.6

    version 0.10 (2017-07-21)
      * Significantly refactored internal stuff behind the scenes
      * `;box measure` now injects the lock difficulty numbers into the measuring output.
      * Now supports wearable lockpicks and other tools.

    version 0.9 (2017-07-01)
      * Added ;box trick <trick> as a convenience shortcut for setting your lockpicking command to use the specified LM trick.
      * Added ;box unlock [<lockpick]> which uses the specified lockpick to relock a box (with Lock Mastery)
      * Added ;box ignore <container>, which prevents ;box for searching from lockpicks and other tools in that container.

    version 0.8.1 (2017-06-23)
      * Improved performance of ;box empty so that it should no longer fail the second part while in RT.

    version 0.8 (2017-06-21)
      * ;box disarm can now accept an item to hold while disarming (like a lockpick or knife)
      * ;box return now stores the last used tool like other commands do.

    version 0.7 (2017-05-13)
      * Possible fix to an issue where lockpick messaging would not always end up in the lockpicking window, and would
        be duplicated in the story window instead (Stormfront Only)
      * Fix HELP being broken for non-rogues (introduced in 0.6)

    version 0.6 (2017-05-12)
      * (StormFront only) add experimental support for copying all lockpicking results to a custom window.
      * add support for DETECT instead of DISARM

    version 0.5 (2017-05-09)
      * add support for calipers using ;box measure (to measure) and ;box calipers (to specify is your calipers)

    version 0.4 (2017-05-06)
      * figure out which lockpick to use before storing the one you were previously holding.  Prevents an issue where
        the container would be updating as ;box searched for the new lockpick, thus causing it to not finding it.

    version 0.3 (2017-05-01)
      * now attempts to return your lockpick from whence it came when emptying a box and prior to accepting a new box.
      * hides locksmith-specific help from non-locksmiths unless they ask for HELP FULL
      * preemptively waitrt in some places to avoid attempting commands that will always fail in roundtime
      * improve ;box scan to use INV CONTAINERS

    version 0.2 (2017-04-27)
      * can now change command used for lockpicking (for use with lockmastery); see ;box COMMAND

    version 0.1 (2017-04-22)
      * initial release
=end


# Messaging for the future
# You carefully begin to examine...

#
# class XMLFilter
#   def initialize(whitelist = ['a'])
#     @whitelist = Set.new(whitelist)
#     @blacklist_depth = 0
#   end
#
#
#
#   @output = []
#   include REXML::StreamListener
# end
#


# We changed BoxScript from a Class to a Module, but that'll fail if the script was already run once this session
# Fix that.
[Object, Scripting].each{|ns| ns.send(:remove_const, :BoxScript) if ns.constants.include?(:BoxScript) } if defined?(BoxScript)


if CharSettings['command'] and CharSettings[:command].nil?
    echo "Migrating settings from an ancient version of box."
    CharSettings[:command] = CharSettings['lockpick_command']
    CharSettings[:calipers] = CharSettings['calipers']
    CharSettings[:window] = CharSettings['window']
    CharSettings[:ignored] = CharSettings['ignored']
    CharSettings[:customer] = {}
    CharSettings['customer'].each{|k, v| CharSettings[:customer][k.intern] = v} if CharSettings['customer']
end

CharSettings[:command] = 'pick $B with $L' unless CharSettings[:command]
CharSettings[:calipers] = 'calipers' unless CharSettings[:calipers]
CharSettings[:window] = 'on' if CharSettings[:window].nil?
CharSettings[:ignored] = Set.new unless CharSettings[:ignored]
CharSettings[:worn] = :first unless CharSettings[:worn]



# We don't want to store this in the DB since it's only relevant for the current session.
# 
unless $_box_script_status
    $_box_script_status = {
        :scanned => false,
        :last_tool => nil,
        :last_box => nil,
        :windowcreated => false,
    }
end

module BoxScript
    attr_accessor :last_tool, :last_box
    VERSION = '0.16 (2020-03-03)'
    BOX_NOUNS = %w(box strongbox chest coffer trunk).to_set
    unless defined?(LOCK_DIFFICULTIES)
        LOCK_DIFFICULTIES = {}
        [
            'primitive', 'rudimentary', 'extremely easy', 'very easy', 'easy', 'very basic', 'fairly easy', 'simple',
            'fairly simple', 'fairly plain', 'moderately well-crafted', 'well-crafted', 'tricky', 'somewhat difficult',
            'moderately difficult', 'very well-crafted', 'difficult', 'extremely well-crafted', 'very difficult',
            'fairly complicated', 'intricate', 'amazingly well-crafted', 'very complex', 'impressively complicated',
            'amazingly intricate', 'extremely difficult', 'extremely complex', 'masterfully well-crafted',
            'amazingly complicated', 'astoundingly complex', 'incredibly intricate', 'absurdly well-crafted',
            'exceedingly complex', 'absurdly difficult', 'masterfully intricate', 'unbelievably complicated',
            'masterfully intricate', 'absurdly complex', 'impossibly complex'
        ].each_with_index{|k, v|
            LOCK_DIFFICULTIES[k] = v
        }
    end
    #echo LOCK_DIFFICULTIES.inspect

    class RingBuffer
        # Only partially implemented -- just what we use.
        def initialize(maxlength)
            @maxlength = maxlength
            @contents = []
            @pos = 0
        end

        def to_a
            # At position 0, or if not full yet, we can return the entire array as-is.
            return @contents.dup if @contents.length < @maxlength or @pos == 0
            return @contents[@pos..-1] + @contents[0..@pos-1]
        end

        def push(what)
            @contents[@pos] = what
            @pos = 0 if (@pos += 1) >= @maxlength
        end
    end

    class ItemResult
        attr_reader :item, :container, :ignored, :worn, :held
        def initialize(item, container: nil, ignored: false, worn: false, held: false)
            @item = item
            @container = container
            @ignored = ignored
            @held = held
            @worn = worn
        end

        def fetch(wait=false)
            @item.inspect
            return false unless @item
            return nil if @held
            return nil if BoxScript.hands.find{|x| x.id == @item.id}
            waitrt?
            if @worn
                fput "remove ##{@item.id}"
            elsif @container
                fput "get ##{@item.id}"
            end
            wait_until_held if wait
            return true
        end

        def wait_until_held  #
            while true
                return if GameObj.right_hand.id == @item.id or GameObj.left_hand.id == @item.id
                waitfor '<right', '<left'
            end
        end

        def wait_until_stored
            while true
                return unless GameObj.right_hand.id == @item.id or GameObj.left_hand.id == @item.id
                waitfor '<right', '<left'
            end
        end

        def store(wait=false)
            return false unless @item
            return nil if @held
            return nil unless BoxScript.hands.find{|x| x.id == @item.id}
            waitrt?
            if @worn
                fput "wear ##{@item.id}"
            elsif @container
                return false unless GameObj.inv.find{|x| x.id == @container}
                fput "put ##{@item.id} in ##{@container}"
            end
            wait_until_stored if wait
            return true
        end
    end

    class StreamWindowBase
        def initialize(id)
            @buffer = []
            @id = id
            @exposed = false
        end

        def created?
            false
        end

        def create(save: false)
            # noop
        end

        def expose
            @buffer << "<exposeStream id='#{@id}' />"
        end

        def write(contents, expose: true)
            contents = contents.join('') if contents.is_a?(Array)
        end
    end

    class CustomStreamWindow
        def initialize
            super('boxresults')
            @buffer = []
            @id = id
        end

        def created?
            $_box_script_status[:window_created]
        end

        def create(save: false)
            return if created?
            window = REXML::Element.new('streamWindow')
            window.attributes['id'] = @id
            window.attributes['title'] = 'Lockpicking'
            window.attributes['ifclosed'] = ''
            window.attributes['scroll'] = 'auto'
            window.attributes['resident'] = 'true'
            window.attributes['save'] = 'save' if save
            @buffer << window.to_s

            $_box_script_status[:window_created] = true
        end




    end


    def self.get_item_patterns(name, strip_my=true)
        words = name.strip.split(/\s+/)
        words.map!{|w| Regexp::escape(w)}

        if words.length == 1  # Just one word
            return [
                /^#{words[0]}$/i,
                /\b#{words[0]}$/i,
                /^#{words[0]}\S+$/i,
                /\b#{words[0]}\S+$/i,
            ]
        end
        return [
            # All words are exact matches.
            /^#{words.join("\\b.*\\b")}$/i,
            # Fully anchored suffix matches.
            /^#{words.join("\\S*\\s+(?:.*\\s+)?")}\S*$/i,
            # All words are prefix matches, not neccessarily anchored
            /\s+#{words.join(".*\\s+")}\S*$/i
        ]
    end

    def self.find_item(what, haystack, strip_my=true, **result_args)
        if what.is_a?(String)
            what = get_item_patterns(what)
        elsif what.is_a?(Regexp)
            what = [what]
        end
        # echo what.inspect
        what.each{|pattern|
            result = haystack.find{|x| x.name =~ pattern}
            return ItemResult.new(result, **result_args) if result
        }
        return nil
    end

    def self.find_item_anywhere(name, strip_my=true)
        patterns = get_item_patterns(name, strip_my)

        result = find_item(patterns, @holding, strip_my, held: true)
        return result if result

        ignored_result = nil

        patterns.each{|pattern|
            pattern = [pattern]

            if CharSettings[:worn] == :first
                result = find_item(pattern, GameObj.inv, strip_my, worn: true)
                return result if result
            end

            GameObj.inv.each{|container|
                next unless container.contents and container.contents.length > 0
                #echo CharSettings[:ignored].inspect
                #echo container.name
                if CharSettings[:ignored].include?(container.name)
                    next if ignored_result
                    ignored_result = find_item(pattern, container.contents, container: container.id, ignored: true)
                    next
                else
                    result = find_item(pattern, container.contents, strip_my, container: container.id)
                    return result if result
                end
            }

            if CharSettings[:worn] == :last
                result = find_item(pattern, GameObj.inv, strip_my, worn: true)
                return result if result
            end
        }

        # If we're still here, we either haven't found anything (in which case ignored_result is nil)
        # Or we've only found something in an ignored container.  Return that.
        return ignored_result
    end

    def self.hands
        return @holding
    end

    def self.wait_until_holding(id)
        wait_until { GameObj.right_hand.id == id or GameObj.left_hand.id == id }
    end

    def self.condense
        result = @buffer.join('')
        @buffer = []
        result
    end

    def self.flush
        result = condense
        unless result == ''
            puts result
        end
        result
    end

    def self.find_boxes(contents, want_closed = nil)
        return [] unless contents
        contents.select {|box|
            next(false) unless BOX_NOUNS.include?(box.noun)
            next(true) if want_closed == nil
            # echo box.contents.inspect
            (box.contents == nil) == want_closed
        }
    end

    def self.find_target_box(pool: true, hands: true)
        @holding.each{|item| return item if item.id and BOX_NOUNS.include?(item.noun) } if hands

        return unless pool
        # Options if we're not holding a box, for the box pool system:
        # - Check all GameObj.loot for something with the character name  ("Akamu's box")
        # - Check all GameObj.loot CONTENTS for something with the character name  ("Akamu's box")
        # - Parse REGET
        # - Try looking on things if an NPC is present.
        #     Bonus: Use mapdb tags?

        pattern = /\b#{Char.name}'s (?:.* )?(?:box|strongbox|chest|trunk|coffer)$/
        # echo pattern.inspect
        if GameObj.loot
            GameObj.loot.each do |container|
                # echo container.name
                return container if container.name =~ pattern
                if container.contents
                    container.contents.each do |item|
                        # echo ">> #{item.name}"
                        return item if item.name =~ pattern
                    end
                end
            end
        end

        id = nil
        noun = nil
        table = nil
        reget.each do |xml|
            if xml =~ /The <a exist="(\d+)" noun="([^"]+)">[^<]+<\/a> is setup .*? <a exist="(\d+)".*for you.*<d cmd='ASK .* ABOUT CHECK/
                id = $1
                noun = $2
                table = $3
            end
        end

        if id
            put "look on ##{table}"
            return GameObj.new(id, noun, "#{Char.name}'s #{noun}")
        end

        # Last-ditch effort using metadata.
        table = find_table
        return nil unless table
        fput "look on ##{table.id}"
        return unless table.contents
        return table.contents.find{|item| item.name =~ pattern}

        return nil
    end

    def self.get_meta_tag(tag)
        rm = Room.current
        return nil unless rm and rm.id and rm.tags
        if rm.tags.find{|x| x =~ /meta:boxpool:#{tag}:(.+)/}
            return $1
        elsif rm.tags.find{|x| x == "locksmith pool"}
            echo "This room is tagged as being a locksmith pool, but does not have meta:boxpool:#{tag}:<name> set.  Please ask someone familiar with the mapdb to fix this."
        end
        return nil
    end

    def self.find_table
        name = get_meta_tag('table')
        return nil unless name
        table = GameObj.loot.find{|x| x.name == name}
        return table if table
        echo "mapdb error: This room is tagged as having '#{table}' as the box pool table, but it does not appear to be present?"
        return nil
    end

    def self.find_npc
        name = get_meta_tag('npc')
        return nil unless name
        npc = GameObj.npcs.find{|x| x.name == name}
        return npc if npc
        echo "mapdb error: This room is tagged as having '#{npc}' as the box pool NPC, but it does not appear to be present?"
        return nil
    end

    def self.filter_items(items, filters)
        unless filters
            return items
        end
        # Convert filter to a list of strings split out by word.
        filters = filters.strip.downcase.split(/\s*[,;]\s*/).map! {|text|
            text_to_words(text)
        }

        filters.map {|filter|
            item = find_matching_item(items, filter)
            unless item
                echo "I could not find your '#{filter.join(" ")}'."
                return nil
            end
            item
        }
    end

    def self.cmd_window(args = nil)
        unless $frontend == 'stormfront'
            echo 'This command is only available in the StormFront FE'
            return
        end
        args = args.downcase.strip if args
        case args
            when 'on', 'true'
                CharSettings[:window] = @window_option = true
                echo 'The locksmithing window is now enabled.'
            when 'off', 'false'
                CharSettings[:window] = @window_option = false
                echo 'The locksmithing window is now disabled.'
            when 'save'
                CharSettings[:window] = @window_option = 'save'
                echo 'The locksmithing window is now enabled, and its window location should now persist across sessions.'
            when 'show'
                unless @window_option
                    echo 'The locksmithing window is currently disabled, and cannot be shown.'
                    return
                end
                expose_window
            when 'clear'
                unless @created_window
                    echo "Cannot clear the locksmithing window because it hasn't yet been created."
                    return
                end
                @buffer << '<clearStream id="boxresults" />'
            when nil
                if @window_option
                    echo 'The locksmithing window is currently enabled.'
                    if @window_option == 'save'
                        echo "The locksmithing window's position will hypothetically be saved in Stormfront across sesssions."
                    end
                else
                    echo 'The locksmithing window is currently disabled.'
                end
            else
                echo 'Subcommand not recognized, expected one of ON, OFF, SAVE, SHOW, or CLEAR.'
        end
        flush
    end

    def self.is_locksmith?
        Stats.prof == 'Rogue' or Skills.disarmingtraps > 0 or Skills.pickinglocks > 0
    end

    def self.cmd_help(args = nil)
        script = "#{$lich_char}#{@script.name}"
        spacer = ''.ljust(script.length, ' ')
        msg = []
        msg << "#{script} version #{VERSION}"
        msg << "Usage:"
        msg << ''
        msg << "   #{script} HELP                Shows this help text."
        msg << ''
        msg << "   #{script} EMPTY [<container>] Open the currently held box, gather the coins, and empty it into the specified"
        msg << "   #{spacer}                     container (or your default lootsack)"
        msg << ''
        msg << "   #{script} GRAB [<container>]  Attempts to grab a closed (and presumably locked) box from the specified "
        msg << "   #{spacer}                     inventory container(s), or any inventory container if none are specified."
        msg << "   #{spacer}                     Separate multiple container names with commas or semicolons."
        msg << ''
        msg << "   #{script} LIST [<container>]  List known boxes in the specifed containers(s), or all containers if no"
        msg << "   #{spacer}                     container is specified."
        msg << ''
        msg << "   #{script} STATUS              Shows your current lootsack and most recent customer."
        msg << ''
        msg << "   #{script} LOOTSACK [<cont>]   Sets/shows your current lootsack.  Note that this affects ALL Lich scripts."
        msg << ''
        msg << "   #{script} SCAN                LOOKs in all of your containers to attempt to force inventory information"
        msg << "   #{spacer}                     to refresh.  Use this if GRAB or LIST are acting up.  Will not examine"
        msg << "   #{spacer}                     closed containers, or containers that are in other containers."
        msg << ''

        if is_locksmith? or args.downcase == 'full'
            msg << "   #{script} ACCEPT [WAIT]       ACCEPT an offer and remember who offered it.  If 'WAIT' is specified, will"
            msg << "   #{spacer}                     wait for an offer if one is not currently pending.  Items that do not look"
            msg << "   #{spacer}                     like boxes will not be automatically accepted."
            msg << "   #{spacer}                     Puts ;box in 'customer mode'"
            msg << ''
            msg << "   #{script} JOB                 Ask the box pool worker for a job."
            msg << "   #{spacer}                     Puts ;box in 'job mode'"
            msg << ''
            msg << "   #{script} RETURN [<player>]   Customer mode: Return the box you recently accepted to whoever offered it to you,"
            msg << "   #{spacer}                     or to <player>."
            msg << "   #{spacer}                     Job mode: Asks the worker to check your work."
            msg << ''
            msg << "   #{script} NEXT [<player>]     Customer mode: Does '#{script} RETURN <player>' and '#{script} ACCEPT wait', in"
            msg << "   #{spacer}                     that order."
            msg << "   #{spacer}                     Job mode: Does '#{script} RETURN' and '#{script} JOB', in that order."
            msg << ''
            msg << "   #{script} DETECT              Detect traps on the currently held box.  Does not attempt to disarm."
            msg << ''
            msg << "   #{script} DISARM [<tool>]     Detect or attempt to disarm the current box, optionally using the specified"
            msg << "   #{spacer}                     tool.  (Specify a tool for traps that require a lockpick or knife to disarm.)"
            msg << ''
            msg << "   #{script} SCARABS [<opts>]    Configures the automatic scarab disarming that can happen as part of ;box disarm"
            msg << "   #{spacer}                     Type `#{script} SCARABS` by itself for more details."
            msg << ''
            msg << "   #{script} UNLOCK [<lockpick>] Unlock the currently held box using the specified lockpick (or the lockpick"
            msg << "   #{spacer}                     currently in your hands).  If <lockpick> consists of multiple words, this "
            msg << "   #{spacer}                     will try to find any lockpick with the same noun and any matching adjectives,"
            msg << "   #{spacer}                     even if those adjectives do not match what the game expects.  For instance, "
            msg << "   #{spacer}                     '#{script} vaalin lockpick' will grab 'a/dark vaalin/lockpick', even though"
            msg << "   #{spacer}                     you would normally need to type 'get my dark lockpick'."
            msg << ''
            msg << "   #{script} RELOCK [<lockpick>] Like UNLOCK, but relocks the box instead using Lock Mastery."
            msg << ''
            msg << "   #{script} FETCH <tool>        Fetches the specified tool using the same matching logic as in UNLOCK."
            msg << "   #{spacer}                     The tool in question will be remembered and returned stored as normal."
            msg << ''
            msg << "   #{script} STORE               Store the tool that was last fetched by returning it to its original location,"
            msg << "   #{spacer}                     if known."
            msg << ''
            msg << "   #{script} CHART [<search>]    Shows a table of lock difficulties, possibly only those matching <search>."
            msg << ''
            msg << "   #{script} RELOCK [<lockpick>] Like UNLOCK, but relocks the box instead using Lock Mastery."
            msg << ''
            msg << "   #{script} CALIPERS [<item>]   Set or show which calipers you are currently using."
            msg << ''
            msg << "   #{script} MEASURE             Measure the box you are holding with your calipers."
            msg << ''
            msg << "   #{script} CALIBRATE           Calibrate your calipers."
            msg << ''
            msg << "   #{script} DROP                Drop your box and return your current tool to where it came from."
            msg << ''
            msg << "   #{script} COMMAND             Shows or changes the current command used to pick boxes.  Useful for using"
            msg << "   #{spacer}                     lock mastery.  Type #{script} COMMAND by itself to see more details on this"
            msg << "   #{spacer}                     option."
            msg << ''
            msg << "   #{script} TRICK <trick>       Sets your lockpicking command to use the specified Lock Mastery trick."
            msg << "   #{spacer}                     Type '#{script} TRICK NONE' to reset to 'normal' lockpicking."
            msg << ''
            msg << "   #{script} WINDOW [<option>]   Configures the lockpicking results window, where <option> is one of:"
            msg << "   #{spacer}                     OFF, ON, SAVE, CLEAR, or SHOW.  WINDOW by itself will show the current "
            msg << "   #{spacer}                     configuration.  Only available in StormFront.  EXPERIMENTAL."
            msg << ''
            msg << "   #{script} IGNORE [<what>]     Ignore the specified container when searching for lockpicks.  Useful"
            msg << "   #{spacer}                     for storing your broken lockpicks.  Use '#{script} IGNORE' by itself"
            msg << "   #{spacer}                     to view the current list."
            msg << ''
            msg << "   #{script} UNIGNORE [<what>]   Stop ignoring the specified container when searching for lockpicks."
            msg << ''
            msg << "   #{script} WINDOW [<option>]   Configures the lockpicking results window, where <option> is one of:"
            msg << "   #{spacer}                     OFF, ON, SAVE, CLEAR, or SHOW.  WINDOW by itself will show the current "
            msg << "   #{spacer}                     configuration.  Only available in StormFront.  EXPERIMENTAL."
            msg << ''
            msg << "#{script} remembers the last tool (lockpick or calipers) that it grabbed and the container that it came from."
            msg << "ACCEPT, NEXT, EMPTY, UNLOCK (if specifying a lockpick) and MEASURE will all return the tool to that same"
            msg << "container if you are still holding the tool and still wearing the container."
        else
            msg << "The above options are most useful for all characters.  For commands primarily of interest to those who"
            msg << "are opening boxes, see #{script} HELP FULL."
            msg << "[Rogues and characters with at least one rank of Lockpicking or Disarming will always see the full help]"
        end
        msg << ''
        msg << "This script is oblivious to items that are in closed containers."
        msg << ''

        respond msg.join("\n")

        cmd_status
    end

    def self.inject_info(line)
        line.gsub!(/Measuring carefully, it looks to be an? (.+) lock\./){|match|
            n = LOCK_DIFFICULTIES[$1]
            next(line) unless n
            n *= 40
            "#{$&}  (Between -#{n == 0 ? 5 : n} and -#{n+35}.)"
        }
        return line
    end

    def self.time_delta(timestamp)
        diff = (DateTime.now - timestamp)
        if diff < 0 # ???
            return "at some point in the wibbly-wobbly timey-wimey future"
        elsif (diff * 86400) < 5
            return "moments ago"
        elsif (diff * 86400) < 90
            return "#{(diff * 86400).to_i} seconds ago"
        elsif (diff * 1440) < 2
            return "about a minute ago"
        elsif (diff * 1440) < 90
            return "about #{(diff * 1440).to_i} minutes ago"
        end
        return "at #{timestamp}"
    end

    def self.cmd_status(args = nil)
        cmd_lootsack(nil)
        cmd_scarab('status')

        if CharSettings[:mode] == :customer
            cust = CharSettings[:customer]
            if cust
                ago = time_delta(cust[:when])
                respond "Currently in CUSTOMER mode.  Your most recent customer was #{cust[:name]}, who offered you #{cust[:box]} #{ago}."
            else
                respond "Currently in CUSTOMER mode.  You have no recorded recent customers."
            end
        elsif CharSettings[:mode] == :job
            if CharSettings[:job_started]
                ago = time_delta(CharSettings[:job_started])
                respond "Currently in JOB mode.  You started this job #{ago}."
            else
                respond "Currently in JOB mode.  You started this job at an unknown time."
            end
        end
    end

    def self.cmd_command(args)
        unless args
            respond "Your current lockpicking command is: #{CharSettings[:command]}"
            respond
            respond "To change it, use '#{$lich_char}#{@script.name} COMMAND command to send', using '$L' in place of your"
            respond "lockpick and '$B' in place of your box.  Some examples:"
            respond
            respond "#{$lich_char}#{@script.name} COMMAND pick $B with $L"
            respond "#{$lich_char}#{@script.name} COMMAND lmas ptrick spin $B"
            respond
            respond "Note: do not use MY in these commands, as an exact reference to the target box and pick is already supplied";
        else
            respond "Your lockpicking command has been changed to: #{args}."
            CharSettings[:command] = args
        end
    end

    def self.cmd_ptrick(args)
        unless args
            respond "Your current lockpicking command is: #{CharSettings[:command]}"
            respond
            respond "To configure #{$lich_char}#{@script.name} to use a particular trick, type:"
            respond "    #{$lich_char}#{@script.name} TRICK <trick>"
            respond "Where <trick> is the name of a lockmastery trick.  Use 'none' to revert to 'standard' lockpicking."
            respond
            respond "For more advanced options regarding your lockpicking command, see #{$lich_char}#{@script.name} COMMAND"
        else
            if args.strip.downcase =~ /^(?:none|clear)$/
                cmd_command('pick $B with $L')
            else
                cmd_command("lmaster ptrick #{args} $B")
            end
        end
    end

    def self.cmd_accept(args, store=true)
        $_box_script_status[:last_tool].store
        unless CharSettings[:mode] == :customer
            CharSettings[:mode] = :customer
            echo "Switching to CUSTOMER mode."
        end
        wait = false
        waiting = false
        if args
            if args.downcase == "wait"
                wait = true
            else
                echo "Use #{$lich_char}#{@script.name} ACCEPT to accept an offer, or #{$lich_char}#{@script.name} ACCEPT WAIT to wait for an offer if needed."
                return
            end
        end
        waitrt?
        fput 'accept'
        loop {
            line = get
            if line == 'You have no offers to accept.'
                if wait
                    waiting = true
                else
                    echo "Use #{$lich_char}#{@script.name} ACCEPT WAIT to wait for an offer before accepting."
                    return
                end
            end
            if line =~ /(You accept <a exist="-?\d+" noun="([^"]+)">.+<\/a> offer and are now holding (?:(.*) )?<a exist="(-?\d+)" noun="([^"]+)">(?:(.*) )?(?:box|strongbox|coffer|chest|trunk)<\/a>\.)/
                message = $1
                customer = $2
                article = $3
                exist = $4
                noun = $5
                adjective = $6

                box_name = [article, adjective, noun].find_all{|x| x}.join(' ')
                CharSettings[:customer] = {
                    :name => customer,
                    :article => article,
                    :adjective => adjective,
                    :noun => noun,
                    :when => DateTime.now,
                    :box => box_name
                }
                box = GameObj.new(exist, noun, "#{adjective} #{noun}".strip)
                echo "Accepted #{box_name} from #{$2}."
                return unless window_allowed?
                checknewbox(box)
                write_window($1)
                write_window("\n")
                _respond condense
                return
            end
            if waiting and line =~ /^<a.*\/a> offers you .* (?:box|strongbox|coffer|chest|trunk)<\/a>.*  The offer will expire in 30 seconds.$/
                waitrt?
                fput 'accept'
            end
        }
    end

    def self.cmd_job(args=nil, store=true)
        $_box_script_status[:last_tool].store
        npc = find_npc
        unless npc
            echo "I can't find the NPC to talk to.  Either you're in the wrong room or map metadata may need to be updated."
            return false
        end
        unless CharSettings[:mode] == :job
            CharSettings[:mode] = :job
            echo "Switching to JOB mode."
        end
        fput "ask ##{npc.id} about job"
        return unless window_allowed?
        nil until get =~ /(?:(<pushBold\/>.*<a exist="#{npc.id}".*says, "(?:.*The <a exist="(\d+)" noun="(.*)"|^\s*|.*))|ASK {entity} ABOUT\/FOR\/TO {subject})/
        return unless $2
        fput "look on table"
        box = find_target_box(hands: false)
        return unless box
        checknewbox(box)
        write_window($1)
        write_window("\n")
        _respond condense

        CharSettings[:job_started] = DateTime.now
    end

    def self.window_allowed?
        $frontend == 'stormfront' and @window_option
    end

    def self.checknewbox(box)
        return unless window_allowed?
        if box.id != $_box_script_status[:last_box].id
            write_window("\n<style id=\"roomName\" />[#{box.name}]\n<style id=\"\" />")
            $_box_script_status[:last_box] = box
        end
    end

    def self.resolve_containers(args)
        if args
            items = filter_items(GameObj.inv, args)
            return unless items
        else
            items = GameObj.inv
        end
        containers = {}
        items.each {|x|
            containers[x.id] = x.contents if x.contents != nil
        }
        return containers
        #
        # return GameObj.containers
    end

    def self.cmd_return(name = nil)
        $_box_script_status[:last_tool].store
        case CharSettings[:mode]
        when :customer
            unless CharSettings[:customer]
                echo "I don't have anybody to return something to."
                return false
            end
            # echo CharSettings['customer'].inspect
            c = CharSettings[:customer]
            name = c[:name] unless name
            waitrt?
            fput "give my #{c[:noun]} to #{name}"  #FIXME
        when :job
            npc = find_npc
            unless npc
                echo "I can't find the NPC to talk to.  Either you're in the wrong room or map metadata may need to be updated."
                return false
            end
            fput "ask ##{npc.id} about check"
        else
            echo "Unknown mode #{CharSettings[:mode]}"
            return false
        end
        return true
    end

    def self.cmd_next(name = nil)
        return unless cmd_return(name)
        case CharSettings[:mode]
        when :customer
            cmd_accept('wait', false)
        when :job
            cmd_job
        else
            echo "Unknown mode #{CharSettings[:mode]}"
            return false
        end
        #
        # unless CharSettings[:customer] or CharSettings[:mode] == :job
        #     echo "I don't have anybody to return something to."
        #     return
        # end
        # return_command(name)
    end


    def self.cmd_list(args)
        containers = resolve_containers(args)
        return unless containers
        boxes = {true => {}, false => {}}

        containers.each {|id, contents|
            find_boxes(contents).each {|box|
                closed = (box.contents == nil)
                if boxes[closed][id] == nil
                    boxes[closed][id] = []
                end
                boxes[closed][id].push(box)
            }
        }

        count = boxes[true].reduce(0) {|memo, (exist, contents)| memo + contents.length}
        if count > 0
            if count > 1
                respond "Found #{count} apparently closed (and presumably locked) boxes:"
            else
                respond "Found #{count} apparently closed (and presumably locked) box:"
            end

            GameObj.inv.each {|container|
                next unless boxes[true][container.id]
                writelink("In your ", container, ":")
                boxes[true][container.id].each {|box| writelink("    ", box)}
                respond
            }
        else
            if args
                respond "You do not appear to have any locked boxes in the specified container(s)."
            else
                respond "You do not appear to have any locked boxes."
            end
        end

        count = boxes[false].reduce(0) {|memo, (exist, contents)| memo + contents.length}
        if count > 0
            if count > 1
                respond "Found #{count} opened (possibly empty) boxes:"
            else
                respond "Found #{count} opened (possibly empty) box:"
            end

            GameObj.inv.each {|container|
                next unless boxes[false][container.id]
                writelink("In your ", container, ":")
                boxes[false][container.id].each {|box|
                    case box.contents.length
                        when 0
                            after = " (empty)"
                        when 1
                            after = " (1 item)"
                        else
                            after = " (#{box.contents.length} items)"
                    end
                    writelink("    ", box, after)
                }
                respond
            }
        end
    end

    def self.cmd_grab(args)
        containers = resolve_containers(args)
        return unless containers
        containers.each {|id, contents|
            find_boxes(contents, true).each {|box|
                # echo box.inspect
                fput "get ##{box.id} from ##{id}"
                return
            }
        }
        echo "I could not locate a locked box on your person."
    end

    def self.cmd_drop(args)
        box = find_target_box(pool: false)
        unless box
            echo "You don't appear to have a box in your hands."
            return
        end
        waitrt?
        $_box_script_status[:last_tool].store
        fput "drop ##{box.id}"
    end

    def self.get_box_and_tool(
        toolname=nil,
        box_not_found: "You don't appear to have a box in your hands or in the pool.  If I'm wrong about the latter, try LOOK ON <whatever container your box is on>.",  # Shown if the box is not found
        tool_not_found: "Could not find that tool.",  # Shown if the tool is not found.
        tool_ignored: "I could only find that item in '%C', which is an ignored container.",  # Shown if the tool is in an ignored container.
        hands_full: "Your hands appear to be full.",  # Shown if hands are full (and the box and tool aren't what's being held)
        no_tool: nil,  # Shown if the non-box hand is empty and no tool was found.  Not an error if nil.
        requires_box: true  # True if we MUST have a box, false if one can be omitted.
    )
        box = nil
        offhand = nil

        @holding.each{|item|
            next unless item.id
            if BOX_NOUNS.include?(item.noun) and box.nil?
                box = item
            else
                offhand = item
            end
        }

        box = find_target_box unless box
        if box.nil? and requires_box
            echo box_not_found
            return nil, nil
        end

        toolname = toolname.strip if toolname

        if toolname and toolname != ''
            tool = find_item_anywhere(toolname)
            unless tool
                echo tool_not_found
                return nil, nil
            end
            if tool.ignored
                echo tool_ignored.gsub('%C', GameObj.inv.find{|x| x.id == tool.container}.full_name)
                return nil, nil
            end
            unless tool.held
                unless offhand.nil? or tool.item.id == offhand.id
                    unless $_box_script_status[:last_tool] and $_box_script_status[:last_tool].store
                        echo hands_full
                        return nil, nil
                    end
                end

                tool.fetch
                $_box_script_status[:last_tool] = tool
                # We don't update the last tool if we're already holding it, because that means we lose the data
                # about what container/etc it originally came from.
                offhand = tool.item
            end
        elsif offhand.nil? and no_tool
            echo no_tool
            return nil, nil
        end
        return box, offhand
    end

    def self.cmd_disarm_detect(args, command)
        if command == 'detect'
            $_box_script_status[:last_tool].store
            args = nil
        end
        box, item = get_box_and_tool(args)
        return unless box

        checknewbox(box)
        waitrt?
        result = capture_command("#{command} ##{box.id}", /(?:^Um, but it's open|(?:You carefully begin to examine|Having discovered a trap|You blink in surprise as though just becoming aware).*<a exist="#{box.id}")/)
        return unless command == 'disarm'

        if result.find{|line| line.include?('You carefully nudge the scarab free of its prison without disturbing the lock too much.  The scarab falls from the lock and onto the ground in front of you.')}
            scarab = GameObj.loot[0]
            if scarab
                if scarab.noun == 'scarab'
                    echo "Found a scarab #{scarab.inspect}"
                    waitrt?
                    if CharSettings[:scarab_disarming]
                        item.store if item
                        case CharSettings[:scarab_method]
                        when :disarm
                            command = "disarm ##{scarab.id}"
                            trigger = /You carefully begin to examine the <a exist="#{scarab.id}" .* for traps\.\.\./
                            CharSettings[:scarab_attempts].times do
                                result = capture_command(command, trigger)
                                return unless result
                            end
                        when :magic
                            ranks = {'4' => Spells.minorelemental, '1' => Spells.minorspirit, '12' => Spells.minormental}
                            possible_spells = []
                            [408, 417, 1218, 119].each do |num|
                                spell = Spell[num]
                                next unless spell.known?
                                possible_spells << spell
                            end

                            if scarab.name == 'sea-green glaes scarab'
                                spell = Spell[114]
                                possible_spells << spell if spell.known?
                            elsif scarab.name == 'sky-blue glaes scarab'
                                spell = Spell[113]
                                possible_spells << spell if spell.known?
                            end

                            unless possible_spells.length > 0
                                echo "No candidate spells found."
                                return
                            end

                            echo possible_spells.inspect

                            spell = possible_spells.min do |a, b|
                                # Compare circle ranks.  Higher is better, so logic reversed
                                n = ranks[b.circle] <=> ranks[a.circle]
                                next n if n != 0
                                # Compare cost, lower is better
                                next a.cost <=> b.cost
                            end

                            echo "Using spell #{spell.inspect}.  Cost #{spell.cost}, ranks in circle #{ranks[spell.circle]}"
                            CharSettings[:scarab_attempts].times do |n|
                                if n == 0
                                    waitcastrt?
                                else
                                    waitcastrt
                                end

                                unless spell.affordable?
                                    echo "Waiting for mana..."
                                    wait_until { spell.affordable? }
                                end
                                spell.cast("##{scarab.id}")
                            end
                        else
                            echo "Unknown scarab disarming method #{CharSettings[:scarab_method].inspect}"
                            return
                        end

                        case CharSettings[:scarab_verb]
                        when nil
                            return
                        when :get
                            fput "get ##{scarab.id}"
                        when :loot
                            fput "loot ##{scarab.id}"
                        else
                            echo "Unknown scarab verb #{CharSettings[:scarab_verb].inspect}"
                            return
                        end
                    end
                else
                    echo "Found a scarab, but the first item in the room is #{scarab.inspect}"
                end
            else
                echo "Theoretically found a scarab, but no loot is in the room?"
            end
        end
    end

    def self.tool_command(
        args,
        template,
        tool_not_found_message,
        tool_ignored_message,
        empty_hands_message,
        requires_box: true,
        &block
    )
        box, item = get_box_and_tool(
            args,
            tool_not_found: tool_not_found_message,
            tool_ignored: tool_ignored_message,
            no_tool: empty_hands_message,
            requires_box: requires_box,
        )
        return unless box or (item and not requires_box)
        checknewbox(box)

        waitrt?
        substitutions = {'$B' => "##{box.id}", '$L' => "##{item.id}", '$T' => "##{item.id}"}
        command = template.gsub(/\$[BLT]/i, substitutions)
        if block_given?
            yield box, item, command
        else
            fput command
        end
    end

    def self.cmd_unlock(args)
        tool_command(
            args,
            CharSettings[:command],
            'I could not find that lockpick.',
            "I could only find that lockpick in '%C', which is an ignored container.",
            'You don\'t appear to holding a lockpick.'
        ) {|box, tool, command|
            capture_command(
                command,
                /attempt \(d100=|attempt \(d100\(open\)=|^Um, but it's open\.|^It does not appear to be locked\./,
                RingBuffer.new(2),
                "\n[Using your #{tool.name}]\n"
            )
        }
    end

    def self.cmd_relock(args)
        box = find_target_box
        if box.contents
            fput "close ##{box.id}"
        end
        tool_command(
            args,
            'lmaster relock $B',
            'I could not find that lockpick.',
            "I could only find that lockpick in '%C', which is an ignored container.",
            'You don\'t appear to holding a lockpick.'
        ) {|box, tool, command|
            capture_command(
                command,
                /attempt \(d100=|^You should close the .* before you try locking it\.|^The .* is already locked!/,
                RingBuffer.new(2),
                "\n[Using your #{tool.name}]\n"
            )
        }
    end

    def self.cmd_measure(args)
        tool_command(
            CharSettings[:calipers],
            'lmas measure $B',
            'I could not find your calipers.',
            "I could only find your calipers in '%C', which is an ignored container.",
            'You don\'t appear to holding calipers.'
        ) {|box, tool, command|
            starttrigger = "Using your <a exist=\"#{tool.id}\""
            stage = 0
            buffer = nil
            timeout = Time::now + 60
            window = window_allowed?

            DownstreamHook.add('BoxScript::WindowCapture', proc {|line|
                DownstreamHook.remove('BoxScript::WindowCapture') if Time::now > timeout
                case stage
                    when 0
                        if line =~ /The .* isn't even closed\./
                            if window
                                write_window(line)
                                line += condense
                            end
                            DownstreamHook.remove('box_capture_script')
                        elsif line.include?(starttrigger)
                            stage = 1
                            buffer = ["\n", line] if window
                        end
                    when 1
                        if line.include?('<prompt')
                            if window
                                write_window(buffer)
                                line += condense
                                buffer = nil
                            end
                            stage = 2
                        elsif window
                            buffer.push(line)
                        end
                    when 2
                        if line.start_with?('Measuring carefully, ')
                            line = self.inject_info(line)
                            if window
                                write_window(line)
                                line += condense
                            end
                            DownstreamHook.remove('box_capture_script')
                        end
                    else
                        nil
                end
                line
            })
            fput command
        }
    end

    def self.cmd_calibrate(args)
        tool_command(
            CharSettings[:calipers],
            'lmas calibrate $T',
            'I could not find your calipers.',
            "I could only find your calipers in '%C', which is an ignored container.",
            'You don\'t appear to holding calipers.',
            requires_box: false,
        ) {|box, tool, command|
            capture_command(command, /(?:You make some effort to fine-tune the <a exist="#{tool.id}"|^Those calipers could not be more perfectly calibrated\.)/)
        }
    end

    def self.cmd_scan(args = nil)
        wanted_downstream = @script.want_downstream
        wanted_downstream_xml = @script.want_downstream_xml
        @script.want_downstream_xml = true
        fput 'inv containers'
        xml = waitfor 'You are wearing'
        @script.want_downstream = wanted_downstream
        @script.want_downstream_xml = wanted_downstream_xml

        # pattern = /<a exist="(\d+)"/g

        xml.scan(/(?:<a exist="(\d+)")+/).each {|match|
            exist = match[0]
            # next if GameObj.containers.include?(exist)
            fput "look in ##{exist}"
            # loop {
            #     line = get
            #     if line =~ /(In .* you see)|(There is nothing in there\.)|(That is closed.)|(Peering into the )/
            #         break
            #     end
            # }
        }
    end

    def self.cmd_ignore(args, ignore)
        if args
            if args =~ /^(?:clear|reset)$/
                CharSettings[:ignored].clear
                echo "Ignored containers list cleared."
                return
            end
            item = find_item(args, GameObj.inv)
            unless item
                echo "Could not find anything matching '#{args}' in your inventory."
                return
            end
            name = item.item.full_name
            if ignore
                if CharSettings[:ignored].add?(name)
                    echo "Added '#{name}' to the ignored containers list."
                else
                    echo "'#{name}' was already in the ignored containers list."
                end
            else
                if CharSettings[:ignored].delete?(name)
                    echo "Removed'#{name}' from the ignored containers list."
                else
                    echo "'#{name}' is not in the ignored containers list."
                end
            end
            return
        end

        list = CharSettings[:ignored].to_a.sort!
        if list.length > 0
            echo "Current contents of the ignored container list: #{list.map{|x| "'#{x}'"}.join('; ')}"
        else
            echo "The ignored container list is empty."
        end
        echo "Use #{$lich_char}#{@script.name} IGNORE <container> to add items to the ignore list."
        echo "Use #{$lich_char}#{@script.name} UNIGNORE <container> to remove items from the ignore list."
    end

    def self.cmd_lootsack(args = nil)
        if args
            UserVars.lootsack = args
            echo "Your lootsack is now '#{args}'"
            return
        else
            if UserVars.lootsack
                echo "Your current lootsack is '#{UserVars.lootsack}'"
            else
                echo "No lootsack is configured."
            end
        end
        echo "You can change this with #{$lich_char}#{@script.name} LOOTSACK <container>"
    end

    def self.find_calipers
        find_item_anywhere(CharSettings[:calipers])
    end

    def self.cmd_calipers(args = nil)
        if args
            CharSettings[:calipers] = args
            echo "Your calipers are now '#{args}'"
        else
            echo "Your current calipers are '#{CharSettings[:calipers]}'"
        end
        calipers = find_calipers.item
        if calipers
            echo "Found '#{calipers.full_name}' (##{calipers.id})"
        else
            echo "WARNING: Could not find any calipers by that description."
        end
    end

    def self.cmd_store(args)
        unless $_box_script_status[:last_tool]
            echo 'No previous tool to store.'
            return
        end
        unless $_box_script_status[:last_tool].store
            echo "Could not store that.  Either you're not holding it, or it came from an unknown location."
            return
        end
    end

    def self.cmd_chart(args)
        args = args.strip
        if args.length > 0
            pattern = /#{args.split(/\s+/).map{|x| Regexp::escape(x)}.join('.*')}/i
        else
            pattern = //  # null pattern
        end

        response = []
        LOCK_DIFFICULTIES.each{|k, v|
            next unless k=~ pattern
            a = v == 0 ? 5 : v*40
            b = v*40 + 35
            response << "#{a.to_s.rjust(4)} to #{b.to_s.rjust(4)}: #{k}"
        }

        #response = []
        #formatted.each{|k, v| response << "#{k.ljust(length, '..',)}: #{v}" }
        respond response.join("\n")
    end

    def self.cmd_fetch(args)
        tool = find_item_anywhere(args)
        unless tool
            echo "I could not find anything matching the description '#{args}'"
            return
        end
        if tool.ignored
            echo "The best I could find was '#{tool.item.full_name}', which was located in the ignored container '#{GameObj.inv.find{|x| x.id == tool.container}.full_name}.'"
            return
        end
        if tool.held
            echo "You are already holding '#{args}'"
            return
        end
        $_box_script_status[:last_tool].store
        $_box_script_status[:last_tool] = tool
        tool.fetch
    end

    def self.run(script)
        # before_dying {
        #     DownstreamHook.list{|hook| DownstreamHook.remove(hook) if hook =~ /^BoxScript::/ }
        # }
        #
        @script = script
        @script.want_upstream = false
        @script.want_downstream = false
        @script.want_downstream_xml = true

        # Buffer of contents to copy to the lockpicking window.
        @buffer = []

        @window_option = CharSettings[:window]

        CharSettings[:mode] ||= :customer

        if CharSettings[:scarab_disarming].nil?
            CharSettings[:scarab_disarming] = false
            CharSettings[:scarab_attempts] = 1
            CharSettings[:scarab_method] = :disarm
            CharSettings[:scarab_verb] = nil
        end

        # Resync what we're holding every time we run
        # We may change this mid-script to 'predict' inventory changes, though.
        @holding = [GameObj.right_hand, GameObj.left_hand].find_all{|x| x.id}

        cmd, *args = script.vars[1..-1]
        if args
            args = args.join(' ')
        end
        if args == ''
            args = nil
        end

        unless cmd
            echo 'No subcommand specified, showing help'
            cmd_help
            exit
        end

        case cmd
            when 'help'
                cmd_help(args)
            when 'list'
                cmd_list(args)
            when 'grab'
                cmd_grab(args)
            when 'accept'
                cmd_accept(args)
            when 'job'
                cmd_job(args)
            when 'return'
                cmd_return(args)
            when 'next'
                cmd_next(args)
            when 'drop'
                cmd_drop(args)
            when 'disarm'
                cmd_disarm_detect(args, 'disarm')
            when 'detect'
                cmd_disarm_detect(args, 'detect')
            when 'unlock', 'pick', 'lockpick'
                cmd_unlock(args)
            when 'relock'
                cmd_relock(args)
            when 'empty'
                cmd_empty(args)
            when 'store'
                cmd_store(args)
            when 'fetch'
                cmd_fetch(args)
            when 'status'
                cmd_status(args)
            when 'scan'
                cmd_scan(args)
            when 'command'
                cmd_command(args)
            when 'trick', 'ptrick'
                cmd_ptrick(args)
            when 'lootsack'
                cmd_lootsack(args)
            when 'calipers'
                cmd_calipers(args)
            when 'measure', 'meas'
                cmd_measure(args)
            when 'calibrate', 'cal'
                cmd_calibrate(args)
            when 'window'
                cmd_window(args)
            when 'ignore'
                cmd_ignore(args, true)
            when 'unignore'
                cmd_ignore(args, false)
            # when 'picksack'
            #   picksack_command(args)
            when 'chart'
                cmd_chart(args)
            when 'scarab', 'scarabs'
                cmd_scarab(args)
            when 'debug'
                echo $_box_script_status.inspect
                echo CharSettings.to_hash.inspect
            else
                echo "Unknown subcommand.  See #{$lich_char}#{@script.name} help."
        end
    end

    def self.cmd_scarab(args)
        # off - Disable scarab disarming
        # on - Enable scarab disarming
        # loot - Also loot the scarab
        # get - Also pick up the scarab

        script = "#{$lich_char}#{@script.name}"
        spacer = ''.ljust(script.length, ' ')
        msg = []

        help = proc {
            msg << "#{script} version #{VERSION}"
            msg << "Options for #{script} SCARABS:"
            msg << "    OFF             - Disables all automatic scarab handling."
            msg << "    ON              - Scarabs will be automatically disarmed as part of ;box disarm"
            msg << "    GET             - ... and also picked up (using GET)"
            msg << "    LOOT            - ... and also LOOTed"
            msg << ''
            msg << "    DISARM          - Scarabs will be disarmed using the DISARM command.  Also turns scarab disarming on."
            # msg << "    MAGIC           - Scarabs will be disarmed using an appropriate magical spell, if able.  Also turns scarab disarming on."
            msg << ''
            msg << "    X##             - Disarm or cast ## time(s) before considering a scarab safe.  The default is one time."
            msg << ''
            msg << "Example:"
            msg << "    #{script} SCARABS DISARM LOOT x3"
            msg << "    #{spacer} Will disarm scarabs three times and then loot them."
            msg << ''
            msg << "Automatic scarab disarming only applies to boxes disarmed with #{script} DISARM.  #{script} tries hard to only target the scarab produced by your disarm attempt, even if another scarab pops up in the interim."
        }
        if args
            args = args.strip.downcase.split(/\s+/)
            if args.include?('help') then
                args = ['help']  # Discard all other args
            end
        else
            args = ['help']
        end

        settings = {}
        args.each do |arg|
            case arg
            when 'help'
                help.call
            when 'off'
                settings[:scarab_disarming] = false
            when 'on'
                settings[:scarab_disarming] = true
                settings[:scarab_verb] = nil
            when 'get'
                settings[:scarab_disarming] = true
                settings[:scarab_verb] = :get
            when 'loot'
                settings[:scarab_disarming] = true
                settings[:scarab_verb] = :loot
            when 'disarm'
                settings[:scarab_disarming] = true
                settings[:scarab_method] = :disarm
            # when 'magic'
            #     settings[:scarab_disarming] = true
            #     settings[:scarab_method] = :magic
            when 'status'
                # quiet noop to suppress help but show configuration
            else
                if arg =~ /x(\d+)/
                    times = $1.to_i
                    if times < 1
                        echo "Feeling like making terrible decisions?  You have to disarm scarabs at least once!"
                        return
                    else
                        settings[:scarab_attempts] = times
                    end
                else
                    echo "Unrecognized suboption '#{arg}'.  See `#{$lich_char}#{@script.name} SCARABS HELP for details`"
                    return
                end
            end
        end

        settings.each {|k,v| CharSettings[k] = v}
        if CharSettings[:scarab_disarming]
            msg << "Scarab disarming is currently ENABLED"
            if CharSettings[:scarab_attempts] == 1
                times = "once"
            else
                times = "#{CharSettings[:scarab_attempts]} times"
            end

            case CharSettings[:scarab_method]
            when :disarm
                msg << "Scarabs will be disarmed using the DISARM command #{times}."
            when :magic
                msg << "Scarabs will be disarmed by casting an appropriate magic spell #{times}."
            else
                msg << "Scarabs will be disarmed using mysterious means known only to those who write buggy code.  (Invalid setting for CharSettings[:scarab_method]!)"
            end

            case CharSettings[:scarab_verb]
            when nil
                msg << "Afterwards, it will be left on the ground"
            when :get
                msg << "Afterwards, it will be picked up"
            when :loot
                msg << "Afterwards, it will be LOOTed"
            else
                msg << "Afterwards, who knows what will happen?  (Invalid setting for CharSettings[:scarab_verb]!)"
            end
        else
            msg << "Scarab disarming is currently DISABLED."
        end
        respond msg

        if CharSettings[:scarab_verb]
            _respond "#{monsterbold_start}WARNING: Automatic scarab looting is experimental.  IT MAY KILL YOU.\r\n(But it shouldn't, unless you just flat out failed the scarab disarm.)#{monsterbold_end}"
        end
    end

    def self.cmd_empty(args = nil)
        $_box_script_status[:last_tool].store
        box = find_target_box(pool: false)
        unless box
            echo "You don't appear to have a box in your hands or in the pool.  If I'm wrong about the latter, try LOOK ON <whatever container your box is on>."
            return
        end

        unless args
            args = UserVars.lootsack
        end
        if args.downcase.start_with?("my ")
            args = args[3..-1]
        end

        waitrt?
        fput "open ##{box.id}" if box.contents == nil
        fput "look in ##{box.id}"
        fput "get coins from ##{box.id}"
        waitfor 'You gather', 'Get what?'
        waitfor '<prompt'
        waitrt?
        fput "empty ##{box.id} into #{args}"
        waitrt?
    end

    def self.create_window(force = false)
        return unless window_allowed?
        return if $_box_script_status[:window_created] unless force

        window = REXML::Element.new('streamWindow')
        window.attributes['id'] = 'boxresults'
        window.attributes['title'] = 'Lockpicking'
        window.attributes['ifclosed'] = ''
        window.attributes['scroll'] = 'auto'
        window.attributes['resident'] = 'true'
        window.attributes['save'] = 'save' if @window_option == 'save'
        @buffer << window.to_s
        $_box_script_status[:window_created] = true
        expose_window
    end

    def self.expose_window
        return unless window_allowed?
        create_window
        @buffer << '<exposeStream id="boxresults" />'
    end

    def self.write_window(contents, expose=true)
        return unless window_allowed?
        create_window
        contents = contents.join('') if contents.is_a?(Array)
        output = []
        output.push("<pushStream id=\"boxresults\" />\n")
        output.push(contents)
        output.push("<popStream />\n")
        @buffer << output.join('')
    end

    def self.strip_most_xml(xml)
        # Keeps <a>
        xml.gsub(/<(?!(?:a )|(?:\/a)).*?>/, '')
    end

    def self.capture_command(command, trigger, buffer=nil, intro="\n", timeout=60)
        # Starts capture when trigger_start happens, and outputs the `context` lines before it.
        # Ends capture when trigger_end happens, and possibly includes that capture in the output
        # Abort if more than a certain amount of time passes to avoid breakage.
        output = nil
        result = []

        if trigger.is_a?(String)
            trigger = Regexp.new(Regexp::escape(trigger))
        end

        begin
            Timeout::timeout(timeout, Interrupt) {
                if window_allowed?
                    DownstreamHook.add('BoxScript::WindowCapture', proc {|line|
                        if line.strip.length > 0
                            if output
                                if line.include?('<prompt')
                                    DownstreamHook.remove('BoxScript::WindowCapture')
                                    write_window(output, false)
                                    line += condense
                                else
                                    output.push(strip_most_xml(line))
                                end
                            else
                                if line =~ trigger
                                    output = [intro]
                                    output += buffer.to_a.map {|line| strip_most_xml(line)} if buffer
                                    buffer = nil
                                    output.push(strip_most_xml(line))
                                elsif buffer
                                    buffer.push(line)
                                end
                            end
                        end
                        next line
                    })
                end
            }
            fput command
            nil until (xml = get) =~ trigger
            result << xml
            until (xml = get).include?('<prompt')
                result << xml.rstrip
            end
        rescue Interrupt
            DownstreamHook.remove('BoxScript::WindowCapture') if window_allowed?
            echo "Timed out waiting #{timeout} seconds for the result of '#{command}'"
            return nil
        end
        return result
    end

    def self.escape_xml(text)
        escape = {'<' => '&lt;', '>' => '&gt;', '"' => '&quot;', "'" => "&apos;", '&' => '&amp;'}
        return text.gsub(/([<>"'&])/) {escape[$1]}
    end

    def self.writelink(before, item, after = nil)
        text = "#{item.before_name} #{item.name} #{item.after_name}".strip
        unless $frontend == 'stormfront'
            respond "#{before}#{text}#{after}"
        end
        puts "#{escape_xml(before)}<a exist=\"#{item.id}\" noun=\"#{item.noun}\">#{escape_xml(text)}</a>#{after}"
    end
end

BoxScript.run(script)