<commit_before>This is documentation for editing scripts.  For general usage and macro information, see [[Jimbly's Macros]]

This reference is now included in the VeggieTales installer under the file name
ScriptingReference.txt

== General Philosophy ==

Most of the existing macros and the macroing interface are all built around a
few primary goals:
* No keyboard interaction.  While a macro is running, the user should be able to freely chat with their friends, navigate between guild tabs, etc.
* Image recognition over offsets.  Where possible, read and scrape the screen to find the exact image we want to click on instead of hardcoding pixel offsets that might change based on resolution or other factors.  The downside of this is that it is more susceptible to minor changes in ATITD causing the macros to work.
* Status and prompts.  Friendly prompts about what values are desired are easy to add, and much better than telling someone to edit the script to handle the values they desire.

== API ==

The functions prefixed with "ls" (short for "LUA script", which makes more sense
in the C++ code, as opposed to the actual macros where *everything* is lua
script...) generally operate on the VeggieTales window, so lsGetWindowSize()
gets the width and height of the VeggieTales window.

The functions prefixed with "sr" (short for Screen Reader) generally operate on
the ATITD window, so srGetWindowSize() gets the width and height of the ATITD
window.

* Note that you *MUST* call srReadScreen to update the screen before calling srFindImageInRange etc.

== Function List ==
=== General ===
  void lsSetCaptureWindow()
  void lsSleep(int ms)
=== Sending Input ===
  void srClickMouse(int x, int y, bool bRightClick)
  void srClickMouseNoMove(int x, int y, bool bRightClick)
  void srKeyEvent(const char *s)
  void srLeftArrow()
  void srRightArrow()
  void srUpArrow()
  void srDownArrow()
  void srDrag(int x0, int y0, int x1, int y1, bool rightClick)
  void srSetMousePos(int x, int y)
  void srMouseDown(int x, int y, bool rightClick)
  void srMouseUp(int x, int y, bool rightClick)
  Vec2 srMousePos()
=== Screen Reading ===
  Vec2 srGetWindowSize()
  Vec2 srImageSize(const char *fn)
  void srMakeImage(const char *name, int x, int y, int w, int h)
  Vec2 srFindImage(const char *fn, int tol)
  void srShowImageDebug(const char *fn, float x, float y, float z, float scale)
  Vec2 srFindImageInRange(const char *fn, int x0, int y0, int w, int h, int tol)
  void srReadScreen()
  int srReadPixel(int x, int y)
  int srReadPixelFromBuffer(int x, int y)
  void srSaveLastReadScreen(const char *fn)
  void lsShowScreengrab(const char *_color)
  Vec2[] lsAnalyzePapyrus(int minsize, int maxsize, int debug, int relevant_radius)
  Vec2[] lsAnalyzeSilt(int minsize, int maxsize, int debug, int relevant_radius)
  [l,t,r,b] srGetWindowBorders(int x, int y)
=== User Interface ===
  int lsScreenX
  int lsScreenY
  Vec2 lsGetWindowSize()
  Vec2 lsMouseClick(int x, int y, int w, int h, int button)
  bool lsMouseIsDown(int button)
  void lsPrintln(const char *s)
  bool lsShiftHeld()
  bool lsAltHeld()
  bool lsControlHeld()
  void lsPlaySound(const char *sound)
  int lsPrint(int x, int y, int z, float xsc, float ysc, const char *color, const char *str)
  void lsFontShadow(int on)
  int lsMessageBox(const char *title, const char *msg, int buttons)
  int lsPrintWrapped(int x, int y, int z, int w, float xsc, float ysc, const char *color, const char *str)
  void lsDisplaySystemSprite(int tile, int x, int y, int z, float w, float h, const char *color)
  bool lsButtonText(int x, int y, int z, int w, const char *color, const char *txt)
  bool lsCheckBox(int x, int y, int z, const char *color, const char *txt, bool value)
  int lsDropdown(const char *key, int x, int y, int z, int w, int val)
  void lsScrollAreaBegin(const char *key, int x, int y, int z, int w, int h)
  void lsScrollAreaEnd(int h)
  void lsSetCamera(float x0, float y0, float x1, float y1)
  void lsDoFrame()
  void lsTopmost(int value)
  {bool done, selection} lsEditBox(const char *key, int x, int y, int z, int w, int h, float xsc, float ysc, const char *color, const char *def)
  int lsGetTimer()

== Specific reference ==
=== void srKeyEvent(const char *s) ===

Sends a character or sequence of characters to the captured window.  Example:
  loadfile("luaScripts/screen_reader_common.inc")();
  function doit()
    askForWindow();
    lsSleep(250); -- wait for shift release to make it to the window
    srKeyEvent('username\tpassword');
    lsSleep(250); -- wait a moment before submitting so we can see it work, that's more fun!
    srKeyEvent('\n');
  end
This will send the string "username" followed by a tab (\t) and then the string
"password" and then enter (\n).
<commit_msg>Updates to scriptingReference to include text functions<commit_after>This is documentation for editing scripts.  For general usage and macro information, see [[Jimbly's Macros]]

This reference is now included in the VeggieTales installer under the file name
ScriptingReference.txt

== General Philosophy ==

Most of the existing macros and the macroing interface are all built around a
few primary goals:
* No keyboard interaction.  While a macro is running, the user should be able to freely chat with their friends, navigate between guild tabs, etc.
* Image recognition over offsets.  Where possible, read and scrape the screen to find the exact image we want to click on instead of hardcoding pixel offsets that might change based on resolution or other factors.  The downside of this is that it is more susceptible to minor changes in ATITD causing the macros to work.
* Status and prompts.  Friendly prompts about what values are desired are easy to add, and much better than telling someone to edit the script to handle the values they desire.

== API ==

The functions prefixed with "ls" (short for "LUA script", which makes more sense
in the C++ code, as opposed to the actual macros where *everything* is lua
script...) generally operate on the VeggieTales window, so lsGetWindowSize()
gets the width and height of the VeggieTales window.

The functions prefixed with "sr" (short for Screen Reader) generally operate on
the ATITD window, so srGetWindowSize() gets the width and height of the ATITD
window.

The functions with neither an sr or ls prefix are lua-script library functions.

* Note that you *MUST* call srReadScreen to update the screen before calling srFindImageInRange etc.

== Function List ==
=== General ===
  void lsSetCaptureWindow()
  void lsSleep(int ms)
=== Sending Input ===
  void srClickMouse(int x, int y, bool bRightClick)
  void srClickMouseNoMove(int x, int y, bool bRightClick)
  void srKeyEvent(const char *s)
  void srLeftArrow()
  void srRightArrow()
  void srUpArrow()
  void srDownArrow()
  void srDrag(int x0, int y0, int x1, int y1, bool rightClick)
  void srSetMousePos(int x, int y)
  void srMouseDown(int x, int y, bool rightClick)
  void srMouseUp(int x, int y, bool rightClick)
  Vec2 srMousePos()
=== Screen Reading ===
  Vec2 srGetWindowSize()
  Vec2 srImageSize(const char *fn)
  void srMakeImage(const char *name, int x, int y, int w, int h)
  Vec2 srFindImage(const char *fn, int tol)
  void srShowImageDebug(const char *fn, float x, float y, float z, float scale)
  Vec2 srFindImageInRange(const char *fn, int x0, int y0, int w, int h, int tol)
  void srReadScreen()
  int srReadPixel(int x, int y)
  int srReadPixelFromBuffer(int x, int y)
  void srSaveLastReadScreen(const char *fn)
  void lsShowScreengrab(const char *_color)
  Vec2[] lsAnalyzePapyrus(int minsize, int maxsize, int debug, int relevant_radius)
  Vec2[] lsAnalyzeSilt(int minsize, int maxsize, int debug, int relevant_radius)
  [l,t,r,b] srGetWindowBorders(int x, int y)
  Vec2[] findAllImages(String imgName, int tol)
=== Text Parsing ===
  Region object is a table where region[0] = x0, region[1] = y0, region[2] = width, region[3] = height
  Parse object is a table where parse[0] = x0, parse[1] = y0, parse[2] = text
  region[] findAllTextRegions()
  parse findText(String s, bool isExact)
  void stripRegion(region r)
  parse[] parseRegion(region r)
  parse findTextInRegion(region r, String t, bool isExact)
  region[] findAllRegionsWithText(String t, bool isExact)
  parse waitForText(String t, int delay, int timeout, bool isExact)
  int waitForNoText(String t, int delay, int timeout, bool isExact)
  region waitForRegionWithText(String t, int delay, int timeout, bool isExact)
  parse waitForTextInRegion(Region r, String t, int delay, int timeout, bool isExact)
  int waitForNoTextInRegion(Region r, String t, int delay, int timeout, bool isExact)
  void clickText(parse p)
  parse[] getChatText()
  parse[] getAllText()
  region srFindInvRegion()
I recommend not using the below functions unless you're modifying lua library functions.
  void srStripScreen()
  void srStripRegion(int x0, int y0, int w, int h)
  region srFindFirstTextRegion()
  region srFindNextTextRegion()
  parse[] srParseTextRegion(int x0, int y0, int w, int h)
  region srFindChatRegion()
  void srTrainTextReader(int x, int y, const char *c)
=== User Interface ===
  int lsScreenX
  int lsScreenY
  Vec2 lsGetWindowSize()
  Vec2 lsMouseClick(int x, int y, int w, int h, int button)
  bool lsMouseIsDown(int button)
  void lsPrintln(const char *s)
  bool lsShiftHeld()
  bool lsAltHeld()
  bool lsControlHeld()
  void lsPlaySound(const char *sound)
  int lsPrint(int x, int y, int z, float xsc, float ysc, const char *color, const char *str)
  void lsFontShadow(int on)
  int lsMessageBox(const char *title, const char *msg, int buttons)
  int lsPrintWrapped(int x, int y, int z, int w, float xsc, float ysc, const char *color, const char *str)
  void lsDisplaySystemSprite(int tile, int x, int y, int z, float w, float h, const char *color)
  bool lsButtonText(int x, int y, int z, int w, const char *color, const char *txt)
  bool lsCheckBox(int x, int y, int z, const char *color, const char *txt, bool value)
  int lsDropdown(const char *key, int x, int y, int z, int w, int val)
  void lsScrollAreaBegin(const char *key, int x, int y, int z, int w, int h)
  void lsScrollAreaEnd(int h)
  void lsSetCamera(float x0, float y0, float x1, float y1)
  void lsDoFrame()
  void lsTopmost(int value)
  {bool done, selection} lsEditBox(const char *key, int x, int y, int z, int w, int h, float xsc, float ysc, const char *color, const char *def)
  int lsGetTimer()
  const char *lsClipboardGet()
  void lsClipboardSet(const char *str)
  void askForWindow(String t)
== Specific reference ==
=== void srKeyEvent(const char *s) ===

Sends a character or sequence of characters to the captured window.  Example:
  loadfile("luaScripts/screen_reader_common.inc")();
  function doit()
    askForWindow();
    lsSleep(250); -- wait for shift release to make it to the window
    srKeyEvent('username\tpassword');
    lsSleep(250); -- wait a moment before submitting so we can see it work, that's more fun!
    srKeyEvent('\n');
  end
This will send the string "username" followed by a tab (\t) and then the string
"password" and then enter (\n).

{'fraction_non_alphanumeric': 0.08268850098974266, 'fraction_numerical': 0.005938456001439625, 'mean_word_length': 4.50520059435364, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '503161', 'n_tokens_mistral': 3609, 'n_tokens_neox': 3414, 'n_words': 1552}