Note: most of these require the new unreleased version of the game to work. I can provide a prerelease to anyone wanting it.
// Logs a warning to the client.log or server.log
warn( String msg )
// Register a block of code with the specified event or events.
// Most of the -init scripts will be mostly these. They can be used in the script
// console but then you should keep track of the result so that you can remove
// it before adding another hook or you will just keep adding more hooks.
EventListener on( EventType type, Closure doIt )
EventListener on( List types, Closure doIt )
// Removes a previously registered hook for the type or types.
void removeHook( EventType type, EventListener hook )
void removeHook( List types, EventListener hook )
// Defines an action that can be run later by group and
// name. This is one of the building blocks of the user-invoked
// tools as well as any eventual object-specific actions.
// When an action is reregistered for a given name and group
// then it has access to the previous version also. There is
// currently no way to remove one of these at runtime once
// registered so (right now) using this in the scripting console
// is not advisable.
void action( Map args, Closure doIt )
// A specific type of action that has no specific group and
// will always be run targeted to an entity.
void entityAction( Map args, Closure doIt )
// Adds a command to the user's shell. This will be changed at
// some point to be shell.addCommand() instead.
void addShellCommand( Shell shell, String name, String description, String help, Closure exec )
// Removes the "object" components from the specified entity and does its
// best to remove the entity completely.
void removePlaceable( EntityId e )
// Returns the numeric cell type of the x,y,z location
int getCellType( double x, double y, double z )
// Returns the numeric cell type of the Vector3i location. Some APIs and hooks
// return positions as Vector3i so this is for convenience.
int getCellType( Vector3i loc )
// Sets the numeric cell type
void setCellType( int x, int y, int z, int type )
void setCellType( Vector3i loc, int type )
BlockType toBlockType( int blockType )
MaterialType toMaterial( int blockType )
Any of those with the last argument "Closure" means that they take a code block "{ some code }"
so,
entityAction( name:"My Action" ) {
// Some code to run when "My Action" is invoked.
}
There is of course a ton more that you can do from scripts. Those are just the convenience APIs that I've built in so far for "root level" stuff.
The other stuff is harder to document. For example, there are a dozen or so "components" for the entity system. "Components" are like typed blocks of data that you can associate with an entity... like Name, Position, etc..
Here are some of them off the top of my head:
ClaimArea
ClaimType
CreatedBy
InContainer
ModelInfo
Name
OwnedBy
Position
Volume (in the physics sense)
Mass
MassProperties
BodyState
And there will be a bunch more eventually.
Some are sort of player specific as associating them with the player entity will cause things to happen on their UI.
For example, ToolActions contains the list of tools that the player has in their mouse scroll wheel set. (This is specific to 'build mode' and will change with 'game mode' but that's another topic.)
More universally, a RadialActions component added to a player will cause their radial menu to popup.
DialogPrompt is the same.
It is my intent to provide more convenient access to these components... but the raw approaches are available even in the scripting console:
// change the name of some entity
entity << new Name( "My Name" )
// get the container of some entity
println entity[InContainer.class].parentId
I haven't wanted to add too many wrappers at this point because things are moving around and it makes maintaining a wrapper API less productive.
Modders can also create their own components and I want to give some thoughts to how they could add their own convenience API also. So if _I_ have a way of mapping entity[InContainer.class] to entity.container then the modders should have similar abilities.
I'm spending a lot of time thinking about this lately and the scripting console is a big start to helping me get things cleaned up and a little more user friendly. Specifically, being able to add and remove hooks is a critical feature and being able to easily add and remove entire plug-ins will be also. I have a beginning design for a more formal plug-in system that will let hooks and actions be associated with a plug-in object that can be loaded and unloaded (within reason).
This weekend I'm focusing on fleshing out "game mode"... this will lead to a lot of scripting goodness also.
