SCriPt v0.7.0

This is an pre-release build. Do not use this on a live server until you know your scripts still execute after updating.

This is a major update to SCriPt and its features. I've done what I can to maintain compatibility with existing scripts but some changes may need to be made.

Built for LabAPI 1.1.4+

Major Changes

• Dynamic Registration

  • Events, Wrappers, and Enums will now be dynamically discovered and registered on plugin load
  • This means if LabAPI adds a new feature or event they are automatically added to SCriPt and can be used in Lua

• Alternate Event Syntax

  • SCriPts recommended way to setup a module is to register events in the load method using Event.SYSTEM.EVENTNAME.add(module.FUNCTION)
  • However, I have added a shorthand version for when a full load function isn't required.

my_module = SCriPt:Mod("My Module")
my_module.on(Events.Server.WaitingForPlayers, function() 
		print('Server is now waiting for players!')
	end)

• Automatic Event Unloading

  • No longer need to .remove your events on unload.
  • They are now automatically removed when a script stops.
  • Manual calls to remove methods will still work as they did before but no longer need the boilerplate.

• API Docs Auto-Gen

  • The plugin will now generate a markdown file at LabAPI/SCriPt/Docs/LuaAPI.md which will contain all available Globals, Enums, and Types with their accessible methods and variables.
  • This will ensure you have a live reference of your current API version.
  • It is a large file to be searched when looking up references.

Other Changes

• Added Aliases for SCriPt global
  • SCRIPT and Script will both work

Fixes

• With the introductions of Dynamic Registration, all missing types and methods from objects are resolved. If the game has them, you have them.

SCriPt v0.6.0

Updated to LabAPI 1.1.2

To Do: Will update documentation with more example scripts to make adding this plugin better.

Additions

• Added events
  • OnPlayerProcessedJailbirdMessage
  • OnPlayerProcessingJailbirdMessage
  • OnScp3114StrangleAborted
  • OnScp3114StrangleAborting
  • OnScp3114StrangleStarting
  • OnScp3114StrangleStarted
• Added MartkdownDocGen class to generate documentation easier
• Added new Globals
  • Player
  • Door
  • Pickup
  • Gives access to public static methods/fields in these classes.

Updates

• Update Round Global
  • Added ExtraTarget Get/Set
  • Added TargetCount Get/Set
• Updated SCriPt Global
  • Added AddStaticGlobal for adding types after load
• Updated Settings Global
  • Added GetSettingOfPlayer(Player, Setting) method
• Patched SSSettings
  • Should now play nicely with other plugins that add menus.

SCriPt v0.5.3

New

• Changed plugin loading to split up script loading process.
  • This will allow for re-adding external dependencies
• Added Cassie.* global to interact with C.A.S.S.E. voices
• Added Warhead.* global to interact with the alpha warhead
• Added new commands lua enable and lua disable
• SCriPt.Settings object can now access settings with mod.my_settings['setting_name']
• Added new accessible object types
  • Door, Pickup, Item, TeslaGate

Changes

• Coroutines now respect AutoYieldCounter from config. This means coroutines will not run infinitely
  • If you would like to run a coroutine infinitely, change the config option AutoYieldCounter to 0. Set at your own risk.

Bug Fixes

• Correctly registered Settings Global

Known bugs

• Cannot interact with AdminToys (Lights, Primitives, Text, etc.)

Wiki has been updated to v0.5.3

SCriPt v0.5.2

SCriPt.LabAPI v0.5.2

New

Added Support for ServerSpecificSettingsSystem, SSSS. This provides clients with a settings panel to decide how they want to interact with your plugin. Has not been fully tested yet.

GlobalSettings

• Button()
• GroupHeader()
• TextArea()
• Dropdown()
• Keybind()
• Plaintext()
• Slider()
• TwoButtons()

GlobalSCriPt

• Settings(Table, Function) -- Create a new SSSettings object, use the Settings.* global to add settings to the table parameter.

Added Time global to give more functions to check and handle time.

GlobalTime

• ServerTimeUtc -- Returns UTC DateTime in milliseconds
• ServerTime -- Return Local DateTime in milliseconds
• RoundTime -- Returns current Round time in total milliseconds
• ServerDateTimeUtc -- Returns DateTime object of UTC time
• ServerDateTime -- Returns DateTImeobject of Local time
• RoundTimeSpan -- Return TimeSpan object of current round time
• MillisecondsToTimeSpan(Number) -- Converts milliseconds to TimeSpan object
• SecondsToTimeSpan(Number) -- Converts Seconds into TImeSpan Object

Additions

GlobalDecon

• Reset()

GlobalPlayer

• All()

GlobalServer

• Port
• PauseIdleMode
• Restart()
• Shutdown()

Player

• Emotion
• Position
• Rotation
• IsSpeaking
• SetRole()
• SendConsoleMessage()
• EnableEffect()
• DisableEffect()
• SendHint()
• SendHitMarker()

CommandDocs

• Added SCriPt.LabAPI as a target for documentation generation.

Changes

• Renamed ObjectiveEvents to match base game naming, all ending with Completed or Completing.
• Moved Custom Command registration inside Module load function. Custom Commands must now be within a module (my_mod.command_a) to be registered now.

Bug Fixes

• Correctly register CustomCommands with Lua

SCriPt v0.5.1

New

• Added new events introduced in LabApi 1.1.1

Events.Objective.*

Completing
Completed
KillingEnemy
KilledEnemy
Escaping
Escaped
ActivatingGenerator
ActivatedGenerator
DamagingScp
DamagedScp
PickingScpItem
PickedScpItem

Events.Scp127.*

GainingExperience
GainedExperience
LevellingUp
LeveledUp
Talking
Talked

Events.Scp3114.* / Events.Skeleton.*

Disguising
Disguised
Revealing
Revealed
StartedDance
StartingDance
StrangleAborting
StrangleAborted
StrangleStarting
StrangleStarted

Updated

Events.Player.*

Jumped
MovementStateChanged
ChangingAttachments
ChangedAttachments
SendingAttachmentsPrefs
SentAttachmentsPrefs
InteractingWarheadLever
InteractedWarheadLever
SpinningRevolver
SpinnedRevolver
ToggledDisruptorFiringMode
ChangedBadgeVisibility
ChangingBadgeVisibility
ProcessingJailbirdMessage
ProcessedJailbirdMessage
InspectingKeycard
InspectedKeycard
RoomChanged
ZoneChanged
RaPlayerListAddedPlayer
RaPlayerListAddingPlayer
ReceivedAchievement
RequestedRaPlayerInfo
RequestingRaPlayerInfo
RequestedCustomRaInfo
RequestedRaPlayerList
RequestingRaPlayerList
RequestedRaPlayersInfo
RequestingRaPlayersInfo

Events.Server.*

ElevatorSequenceChanged

SCriPt v0.5.0

Full Rewrite to LabAPI 1.1.1

Note: Support will be limited for the time being. Working on Documentation.

Name is a combination of "script" and "SCP", "SCriPt"

Primary Features

• Write Lua code that will perform actions inside SCP:SL
• Subscribe to game events to run code when you want it.
• Can make anything from a round setup script, custom commands, Coroutines, placing toys, and even a full plugin.
• Restricted access for scripts to not talk to eachother directly
• Data Global to store and retrieve persistent information including immutable entries
• Documentation with getting started can be found at https://tayjay.github.io/SCriPt/LabAPI

Requires MoonSharp.Interpreter.dll be placed in /LabAPI/dependencies/global/. File is included.

Scripts to be placed in `/LabAPI/SCriPt/Scripts

Full Changelog: v0.4.0-alpha...v0.5.0-alpha

SCriPt v0.4.0

Updated to EXILED 9.6.0

Note: Not fully tested but existing scripts appear to load without issue. Support will be limited for the time being.

• Changed file location for scripts to be under the "EXILED" directory, beside the Config and Plugins directories
  • Windows: %appdata%\EXILED\SCriPt\
  • Linux: /home/scpserver/.config/EXILED/SCriPt/
• Added proxy classes for all playable roles, can now call functions and get values based on a player's role.
  • Example:

    -- Where player is Peanut
    if player.Role.Type == RoleType.Scp173 then
      player.Role.BlinkReady = true
    end

• Added AdminToy support
  • Docs to follow eventually

SCriPt v0.3.0

Major Changes

Scripts Directory

• Script loading structure has changed.
• All scripts in the Scripts directory, other than those in the "Globals" subdirectory are now loaded on startup recursively.
  • Any scripts in subdirectories like AutoLoad will work as expected.
• Scripts now all load on plugin startup into their own containers
  • No more "AutoLoad" script
  • This is to increase security and allow for easier expansion of the plugin
• Wiki has been updated to reflect the change

Config Changes

• Make sure to regenerate the "s_cri_pt > script_path config option to allow the new script loader to function correctly.

Backend Changes

• Changed how a script is loaded to more easily keep track of its lifecycle.
• Coroutines, Command, and other objects a script creates are now tracked independently, and can be removed cleanly when a script is unloaded.

Enums

• Enum types are now registered for scripts
• This means that functions that used to values like player role will now use C# enum syntax rather than name
  • Player:SetRole("ClassD") is now Player:SetRole(RoleTypeId.ClassD)
• Information on some of these Enums can be found in the EXILED documentation

EXILED Custom Items support

Starting to work on adding support for registering custom items within Lua. This implementation is still WIP.

Creating a script with the following content will create a custom gun:

custom_gun ={
  firearm_type='Com15',
  name='CustomCom15',
  description='It's a custom gun',
  weight='1',
  damage='100'
}

function custom_gun.OnShooting(args)
  print('Shooting')
  args.IsAllowed=false
end

New Pastebin Implementation

• The Pastebin global has been removed.
• There is now a new process to load scripts from Pastebin
  • Create a new file in the same directory as your other scripts.
  • Name the file with the name of the link you wish to reference and the file extension .pastebin
  • Example: KUJHSZM2.pastebin (This will load the SkeletonCommand.lua example file https://pastebin.com/KUJHSZM2)
• When the server starts it will download the script, in this example to KUJHSZM2.lua, and execute it like any other
• Changes can be made to this lua file as you wish
• If you'd like to revert to the original script, or if a new version of that pastebin has been updated:
  • Delete the generated .lua file.
  • The existing .pastebin file will automatically redownload it.
• Saving the script and not downloading on every load will accomplish the following
  • Reduce network usage
  • Reduce impact if the original pastebin is tampered with
  • Allow for customization of the downloaded scripts.

Minor Changes

• Added Events.Warhead.* events handler
• Added Facility.Seed variable
• Added Lobby.TimeLeft
• Added a New global to scripts
  • Allows creating some new structs
  • New.Vector3(x,y,z), New.Color(r,g,b,a)
• Store will no longer automatically save, if you make a change you are responsible for saving it
  • Was taking a lot of resources when not in use.
• For Player objects
  • Added methods to enable, disable, and check on player effects by EffectType enum
  • Can now set role based on RoleTypeId enum
  • Get and set a player's ScpTickets
  • Get a player's DoNotTrack status
  • UseHeldItem and UseItem(ItemType) methods for forcing interaction with items
  • MovementState variable of type PlayerMovementState to get and set how a player is moving
  • EnableFallDamage get and set
  • Added method CheckPermission(String) to see if the player has a specific EXILED permission
• Server Events
  • Added SelectingRespawnTeam event

SCriPt v0.2.0

New Custom Commands

• Added a way to create custom commands through Lua scripts.
• Works with RemoteAdmin and client console commands
• Commands are registered with the server, and work with auto-complete and help command.
• See docs for information on making your first command
• Commands are created as separate scripts in the Scripts/Commands/ directory

New Custom Config

• Lua scripts can now call the 'Config' global to save and load values to a json config file to allow for script customization without modifying the original code.
• Example:

  • spawn_chance = Config:Load("BaseSpawnChance", 25)

  • Will return the default value of 25 if the value is not saved already and add it to the file, subsequent calls to the load function will return the value saved to disk
• Config values saved to Scripts/Data/config.json in 1 file.

New Persistent Storage

• Lua scripts can now store and recall data between loads
• Similar to Config system but with read and write, and more complex data types.
• Example:

  • stored = Store:Load('my_data',${
      default=0
    })

  • Loads a table "my_data" from storage.
  • If the table does not exist, it will populate with the provided second argument, if no argument is provided an empty table is created.
  • Table must follow "Prime Table" requirements
    • Can only contain: Numbers, Strings, Booleans, and other Prime Tables
• Tables are stored in Scripts/Data/store.json, but are meant to be accessed in code only.

Improved Coroutines

• Timing global object is now context aware of what script it is running in.
• When a script is unloaded, all MEC coroutines that it created are automatically killed.

Improved Logging

• Using the print() function in Lua will now include the script's name in the console output, so you know which script is talking.
• Old [Lua] Message
• New [Lua-Scripts/Folder/Name.lua] Message

Testing Pastebin Scripts

• Added a Pastebin global function to scripts
• Calling with the the parameter of a script file saved to pastebin, the last part of the url, it will load and run the script.
• Pastebin scripts cannot be ran if configs are set more permissive than the default. Limited|SoftSandbox
• "allow_pastebin" config option must also be set to true, leaving false by default.
• In an empty lua file just call Pastebin('xxxxxxxx') directly and it will execute the code located there on load.
• The location of this file will determine when it is executed.
• Scripts on Pastebin will also not be executed if they attempt to call another pastebin script.

New

• Patched to EXILED OFFICIAL 8.11.0
  • Added Scp939 event PlayingFootstep
  • New properties on existing events automatically apply to scripts
• New command script reload
  • Will unload all scripts, then load AutoLoad scripts again.
• Added globals to create structs such as Color, Vector3, and Quaternions inside Lua directly.
• Updated API to allow access to Scripts' Config and Store data objects through their PluginConnector
• Updated Docs to reference new features above

SCriPt v0.1.0

First Official Pre-release!

This should be a functional build of the SCriPt plugin. The name is an attempt to combine "SCP" and "script".

Please read the documentation from this repo's Wiki. It includes examples of what can be done with the plugin. You'll require the MoonSharp library for this plugin to run, information on that can be found in the Getting Started guide.

Features

• Write .lua files that execute code when EXILED events are fired.
• Configuration options to change how much access the plugin has to your host (Defaults give limited access, but can go as far as running system commands when events trigger if you so choose)
• No compiling of C# libraries to prototype changes
• Allowing Server owners automation options that hook into the game without writing a plugin.
• A basic API bridge for other plugins to expand on what this plugin can do, and expose their own code to be accessible in scripts. See my main plugin collection, TTPlugins, for an example.
• Connects Lua Coroutines with EXILED's MEC to run code asynchronously. (Config option to limit code execution from infinite loops, but can be disabled for permanent loops)
• Exposes several EXILED classes and functions using Lua Globals

Known Issues

• There are bugs, lots, please report them so I can fix them next patch.
• Not all classes are registered types for use in scripts. This is a technical limitation. "Proxy Types" have been made for some of the commonly used types in EXILED that give access to fields and methods of things like Players, Doors, Rooms, Pickups, Items, etc.
  • Please report any common types that are missing, or try adding them yourself using a custom Lua Global file. These instructions will be in the Docs soon.
• The lua command for running scripts in game is WIP, you may see varying results, scripts need to be in the root Scripts directory to be executed.

Installation

The Docs have full instructions but here are the basics. Download the SCriPt.dll plugin from here, place it in your Exiled plugins folder. Download the dependencies.zip from here, or follow the docs to get it from the official source and extract it in the EXILED/Plugins/dependencies subfolder. Run your server once to generate the required configs and Script folders. Try writing your first script and place it in the Scripts/AutoLoad folder so it runs on startup (located in the same directory as the "localadmin" install).