The language
Scripts are in Groovy, a modern and quite easy computer language, maintained by the Apache Software Foundation.
See a full documentation of groovy, and more informations, on the official website. As a script writer, you do not need to read it.

The files
Scripts must be in a file with a .groovy extension. There may be more than one file (one file can call another). This (or these) file(s) must be in the scripts/ folder of the SexScripts software (may be in a subfolder).
Pictures, videos and sounds should be in some subfolders of images/, videos/ and sounds/.
All will be compacted and sent to the website if you use the publish function of the editor. All will be put in the good corresponding folders when any user downloads it (desktop and Android versions).

How to begin ?
You should have read the user documentation, which include "How to create a script from..." (Picture gallery, Cybermistress, Milovana).
Then see the chapters below : How to start (I am a programmer), How to start (I am not a programmer).
The editor is bundled with the main software. But you may instead use ssScriptMaker, an extension to easily write scripts in a very few mouse clicks without any need of programming, or any text editor.

You know things about programming (VBA ? C++ ? Python ? ...) : good news, it isn't more difficult than that, the SexScripts language is Groovy (a simple language close to Java and Ruby), with some specific methods.

• Launch the SexScripts software, then Menu>Script>Edit.
• Open simpleexample.groovy.
• Read quickly
• Open test.groovy.
• Read carefully.
• Ask any question on this forum

That's it, you know how to create scripts.

Writing scripts is far from being difficult. You have to write some orders to the tool (show something, set image ...: the "functions" listed below), and they will be executed one after one.
The syntax is mildly strict, if you make some mistakes, they'll be showed to you to be corrected.

Main details:
* A script is a text file (with some images, ... linked from it)
* Each order is on a line of that text file, line that may (no consequence) end with a ";" (semicolon)
* You can add spaces, tabs and line returns anywhere in the script
* Uppercase letters and lowercase letters are not the same
* A line beginning with "//" (two slashes) will be ignored, it's a comment.

Here is a quick start method for you:
* Launch the SexScripts tool, then Menu>Script>Edit.
* Open simpleexample.groovy (Menu>File>Open).
* Read carefully
* Try to create a new script (Menu>File>New). There are some basic instructions in the file created, you just have to complete and save
* Test it (in the main window, Menu>script>Restart), correct it, expand it, test it, ...
* Come back here to ask any question (there are no stupid ones).

More ?
* There is a very good and complete manual/FAQ available in this thread.

See also tag reference

Functions are, with operators and various keywords, one of the things composing the language of SexScripts. It is the specific thing, the rest belonging to the base language, Groovy. Right-click in the editor to get some code snippets for them.

The most important functions are in red, beginners and intermediate script authors can ignore black functions. Things between brackets [], like "[, String yesText, String noText]" below, are optional.

There is a test case for most of these functions in the standard script test.groovy.


exit()
Exits software (on the contrary, simply type return null to exit script).

getBoolean(String message [, String yesText, String noText])
Asks user to click yes or no, returns it (true or false). Set a yesText and a noText to avoid the standard texts ("Yes" and "No" in english). message will erase text (null to avoid this).
Examples : def b1 = getBoolean("Ok ?"); def b2 = getBoolean("Sure ?", "Yes", "Quite") ;

getBooleans(String message, String[] texts, String[] defaultValues)
Asks user to click some checkboxes, returns an array of boolean (true/false).

getDataFolder()
Returns a text string, the directory containing the images, sounds, videos folders, with the trailing slash. Use this instead of direct relative paths, when accessing some files in standard Java except of using this API functions.
Example : def dir = getDataFolder(); new File(dir+"/images/myscript/x.jpeg").renameTo(dir+"/images/myscript/y.jpg")// (and not simply new File("images/myscript/x.jpeg")...)

getFile(String message)
Asks user to choose a file, returns its full name, its full path included (or null if they cancelled).

getFloat(String message, Float defaultValue)
Asks user to write a number (perhaps with decimals). message will erase text (null to avoid this).

getImage(String message)
Use the webcam to take a picture. Returns its full name, its path included. If no webcam found, run getFile() instead.

getInteger(String message, Integer defaultValue)
Asks user to write a number, returns it. message will erase text (null to avoid this).

getSelectedValue(String message, String[] texts)
Asks user to select a value (string) among some. It will show a dropdown list, or some buttons, depending on space available and texts size. message will erase text (null to avoid this). Returns the index number of this value (the first one is numbered 0, not 1).

getString(String message, String defaultValue)
Asks user to write something, returns it (or null if they cancelled). message will erase text (null to avoid this).
Example : def c = getString("What is your favorite color ?", "")

getTime()
Returns an big integer, the number of seconds since 01/01/1970

getRandom(max)
Returns a random number between 0 and max (excluded).
Example : if(getRandom(2) == 0) ...

isConnected()
Returns true if there is a connection to the internet and to the main SexScripts server.

load(String key)
Reads from the data file a value associated with a key, returns it. The result may be of type boolean, integer, double, string, list of anything or map of anything. Returns null if not found.

loadBoolean(String key)
Reads from the data file (data.properties) a boolean (true/false) associated with a key, returns it. Returns null if not found. Use this for example to know if user is a woman : def isWomen = loadBoolean("intro.women");. More info : see the file data.properties (open it with notepad, vi or any other text editor).

loadFirstTrue(String ... keys)
Reads from the data file some booleans, returning the first one that is true. Example : loadFirstTrue("a","b") will return "a" if there is "a=true" in data file, else "b" if there is "b=true", else null. Useful for toys and clothes options.

loadFloat(String key)
Reads from the data file a floating number associated with a key, returns it. Returns null if not found.

loadInteger(String key)
Reads from the data file a number associated with a key, returns it. Returns null if not found.

loadMap(String key)
Reads from the data file a full map (String=>anything) of data associated with a key, returns it. Returns null if not found.

loadString(String key)
Reads in data file a character string associated with a key, returns it. Returns null if not found.
Example : show("Hello "+loadString("intro.name"))

openTrays()
Try to open all CD trays. If the device have no CD trays, but can vibrate, it will vibrate instead.

playBackgroundSound(String filename [, Integer times = 1])
Plays sound (.wav or .mp3 file must be in "sounds/" directory, or in a sub-directory). Does not wait for the end of the sound. Set filename to null to stop all sounds. The parameter "times" is optional, the sound will play "times" times (default value : 1).

playSound(String filename)
Plays sound (.wav or .mp3 file must be in "sounds/" directory, or in a sub-directory). Waits for the end of the sound, then continues.

receive(String key)
Reads from the online data file a value associated with a key, returns it. The value may be of type boolean, integer, double, String, list of anything or map of anything. Returns null if not found.

receiveBoolean(String key)
Reads from the online data file a boolean (true/false) associated with a key, returns it. Returns null if not found.

receiveFloat(String key)
Reads from the online data file a floating number associated with a key, returns it. Returns null if not found.

receiveImage(String code)
Reads from the online server a picture associated with a code (from sendImage()), write it locally. Returns the full file path of the new local file. Returns null if not found.

receiveInteger(String key)
Reads from the online data file an integer number associated with a key, returns it. Returns null if not found.

receiveString(String key)
Reads from the online data file an character string associated with a key, returns it. Returns null if not found.

return name
(this is a keyword, not a function) Stops the script and starts another one (or none if the name is null). The name is the name of a script, it should not end by ".groovy", but should start by the subdirectory, if any (with / to separate the directories, and taking care of the character case).
Example : return "clothes" //will stop the current script and start scripts/clothes.groovy
Example : return null

save(String key, * value)
Saves something (String, Integer, Float, Boolean, List, Map) in the datafile. Put null value to erase it (anyway, everything corresponding will be deleted before overwritten). The key must contains only letters, digits, dots, dashes (regexp : ^[\w\.\-]+$). See also load(), loadBoolean(), loadInteger(), etc.

send(String key, * value)
Sends something (String, Integer, Float, Boolean, List, Map) in the online datafile. Put null value to erase it (anyway, everything corresponding will be deleted before overwrited). The key must contains only letters, digits, dots, dashes (regexp : ^[\w\.\-]+$). See also receive(), receiveBoolean(), receiveInteger(), etc.

sendImage(String filename)
Sends an image file to the server (in a restricted location). Returns a character string, a code to load back the image file with receiveImage() later. Returns null if failed (not a picture, etc.). Big pictures are automatically scaled down.

setImage(String filename)
Shows image (file must be in "images/" directory, perhaps in a sub-directory).
Extensions jpg, jpeg, png, gif are supported (even with transparency). If filename is null, it shows nothing.
(There is a cache system for pictures : if you update the file then show it again with setImage(), it may show the previous version.)
Example : setImage(null)
Example : setImage("myscript/picture4.jpeg")

setImage(byte[] bytes, int useless)
Shows image, being an array of bytes (see a full sample in test.groovy). The second parameter is useless now.

setImage(Image image, boolean useless)
Shows image, being a full java.awt.Image object. The second parameter is useless now. This method is deprecated since API 5, replaced by setImage(byte[] bytes, int useless), because java.awt is not available in android

setInfos(Integer version, String title, String summary, String author, String status, Integer color, String language, String[] tags)
Indicates some informations about this script. Put this one time at the start of the script. See template file (when creating a new script) for more informations.

show(String message)
Shows a simple message.
Example : show("About this : \n\nThat !")

showButton(String text[, Float seconds])
Shows a button with some text inside, after main text. Blocks script. Returns number of seconds waiting user's click.
May receive a second parameter, in seconds. If so, stops waiting after this duration and then hide the button and continue.
Example : showButton("Please quick click !", 3)

showPopup(String text)
Shows a popup window with some text inside. Returns number of seconds waiting user click on [Ok].

useEmailAddress(String address)
Asks the system to start the tool associated with email sending (Outlook, Mail, ...), with the receiver address as a parameter.

useFile(String filename)
Asks the system to open the document (video, sound...), based on his name and extension (using "start" on Windows, "open" on Mac, "xdg-opn" on Linux, "start-activity" on Android). filename should be relative to the root directory of SexScripts, for example "video/myscript/sexy.avi".

useUrl(String url)
Asks the system to open the URL ("https://....") in the default web browser.

wait(Float seconds)
Blocks script during some time.
Example : wait(0.5)

waitWithGauge(Float seconds)
Blocks script during some time, showing a gauge.


This is the API 9. If someone starts a script that uses the API 9 with an old release of SexScripts, a message will appear, asking to download a newer release.

You want more functions ? Something is missing ? Feel free to post in this forum.

Most Java/Groovy functions are available for script writers. Beware :

• They are, in the documentation above, shared among "classes", themself among "packages"
• When they belong to a class not in the package "java.lang", code will be more verbose (eg : java.util.Calendar c = java.util.Calendar.getInstance() )
• Most of them (95% of 20,000) are "instance methods", that means it is quite difficult to use them (if you know nothing about programming, especially OOP).

Here are some functions quite easy to use and useful :

Calendar.getInstance().get(int constantForWhatToGet)
Return a number, one part of the current Date. Parameter is a constant, prefixed by "Calendar", there are YEAR, MONTH, (0..1) DAY_OF_MONTH (1..31), DAY_OF_WEEK (1..7), HOURS_OF_DAY (0..23), MINUTE, SECOND.
Example : def y = Calendar.getInstance().get(Calendar.YEAR)

Math.floor(Float value)
Returns a number rounded to the nearest integer below.
Example : def x = 0.8, y = Math.floor(x)

Math.round(Float value)
Returns a number rounded to the nearest integer.
Example : def x = 0.8, y = Math.round(x)

Math.sqrt(Float value)
Returns the square root of a number.
Example : def x = Math.sqrt(16)

String.format(String format, * value1, * value2...)
Returns a text string, formatting numbers. The format is a text string, with some special expression indicating formatted values. Each of this expression follows this form : %[options][type]. Type may be "d" (decimal), "f" (floating number), "s" (string)... And each type has some options, for example "f" may have the number of digits after a dot.
Example : def x = 1.23, s = String.format("%d", x) // s contains "1"
Example : def x = 1.23, s = String.format("%d - %f - %.1f - %.3f", x, x, x, x) // s contains "3 - 1.23 - 1.2 - 1.230"

You may be identified 2 times : with an account in this forum (used only in the website forum), and in scripts ("author" in script, shown in the Scripts web page). Anonymous in the forum may read but not write. "Anonymous" as an author name in scripts is quite allowed.

One relation between those two authentications : if the same, when publishing, there will be a link on your username to your forum identity in the Scripts page.

Using the scripts is anonymous, except stated otherwise ("internet" tag). The SexScripts software itself does not automatically "phone home" - it'll connect only, anonymously, when opening the about box (to get the version), downloading a script, and using some "internet" scripts. IP address is then temporary stored on the SexScripts server to mitigate some possible hacking attempts.

GDPR informations for european users : we don't know your personal informations ; we don't want to know your personal informations ; you must avoid to give anything about your personal informations here (names, age, location, ...). Using SexScripts, you send your data to those third parties : Alphabet by Google Analytics on the web site (website traffic), and Fyber by Heyzap on the Android application (advertising).

Those functions use the communication API (from API 6 upward) : isConnected(), receive(), receiveBoolean(), receiveFloat(), receiveImage(), receiveInteger(), receiveString(), send(), sendImage().

Communications are encrypted if possible ; they use HTTPS over TCP, from the client (the main software) to the server (https://ss.deviatenow.com), or degrade to HTTP if needed (Java 6 for example).

There are limits encoded in the client software and on the server. The most noticeable are a soft limit on the number of calls per day (and also per session). When those limits are reached, some pesky additionnal delays are added (more and more). Mainly : maximum 50 calls (in total, using any of the function above) for one script.
Another limit is the size of data for the send() function : 1 kilobyte for the key, 10 kilobytes for the value (or values).

As a consequence, for now, the API is not suitable for synchronous communication (a chat application or things like that) or massive communication (image gallery, etc.).


As a user, you should not try to overstep those limits (by modifying the client software for example). It will fail, and you'll be banned.

As a developer :

• ponder your idea of script (ask about it)
• check for those limits in your code
• try to do some simple optimizations : read each thing only once, etc.
• among those optimizations (since API 8), write and read full maps of data (with save() and receive()) instead of individual values one by one

If you have any question, please feel free to ask on the forum.