Documentation
¶
Overview ¶
Package cmd implements a Minecraft specific command system, which may be used simply by 'plugging' it in and sending commands registered in an AvailableCommandsPacket.
The cmd package handles commands in a specific way: It requires a struct to be passed to the cmd.New() function, which implements the Runnable interface. For every exported field in the struct, executing the command will result in the parsing of the arguments using the types of the fields of the struct, in the order that they appear in. Fields unexported or ignored using the `cmd:"-"` struct tag (see below) have their values copied but retained.
A Runnable may have exported fields only of the following types: int8, int16, int32, int64, int, uint8, uint16, uint32, uint64, uint, float32, float64, string, bool, mgl64.Vec3, Varargs, []Target, cmd.SubCommand, Optional[T] (to make a parameter optional), or a type that implements the cmd.Parameter or cmd.Enum interface. cmd.Enum implementations must be of the type string. Fields in the Runnable struct may have `cmd:` struct tag to specify the name and suffix of a parameter as such:
type T struct {
Param int `cmd:"name,suffix"`
}
If no name is set, the field name is used. Additionally, the name as specified in the struct tag may be '-' to make the parser ignore the field. In this case, the field does not have to be of one of the types above.
Commands may be registered using the cmd.Register() method. By itself, this method will not ensure that the client will be able to use the command: The user of the cmd package must handle commands itself and run the appropriate one using the cmd.ByAlias function.
Index ¶
- Variables
- func AddTargetFunc(f TargetFunc)
- func Commands() map[string]Command
- func Register(command Command)
- type Allower
- type Command
- func (cmd Command) Aliases() []string
- func (cmd Command) Description() string
- func (cmd Command) Execute(args string, source Source)
- func (cmd Command) Name() string
- func (cmd Command) Params(src Source) [][]ParamInfo
- func (cmd Command) Runnables(src Source) map[int]Runnable
- func (cmd Command) String() string
- func (cmd Command) Usage() string
- type Enum
- type Line
- type NamedTarget
- type Optional
- type Output
- func (o *Output) Error(a ...any)
- func (o *Output) ErrorCount() int
- func (o *Output) Errorf(format string, a ...any)
- func (o *Output) Errors() []error
- func (o *Output) MessageCount() int
- func (o *Output) Messages() []string
- func (o *Output) Print(a ...any)
- func (o *Output) Printf(format string, a ...any)
- type ParamInfo
- type Parameter
- type Runnable
- type Source
- type SubCommand
- type Target
- type TargetFunc
- type Varargs
Constants ¶
This section is empty.
Variables ¶
var ErrInsufficientArgs = errors.New("not enough arguments for command")
ErrInsufficientArgs is returned by argument parsing functions if it does not have sufficient arguments passed and is not optional.
Functions ¶
func AddTargetFunc ¶
func AddTargetFunc(f TargetFunc)
AddTargetFunc adds a TargetFunc to the list of functions used to find targets that may be targeted by a Source.
Types ¶
type Allower ¶
type Allower interface {
// Allow checks if the Source passed is allowed to execute the command. True is returned if the Source is
// allowed to execute the command.
Allow(src Source) bool
}
Allower may be implemented by a type also implementing Runnable to limit the sources that may run the command.
type Command ¶
type Command struct {
// contains filtered or unexported fields
}
Command is a wrapper around a Runnable. It provides additional identity and utility methods for the actual runnable command so that it may be identified more easily.
func ByAlias ¶
ByAlias looks up a command by an alias. If found, the command and true are returned. If not, the returned command is nil and the bool is false.
func New ¶
New returns a new Command using the name and description passed. The Runnable passed must be a (pointer to a) struct, with its fields representing the parameters of the command. When the command is run, the Run method of the Runnable will be called, after all fields have their values from the parsed command set. If r is not a struct or a pointer to a struct, New panics.
func (Command) Aliases ¶
Aliases returns a list of aliases for the command. In addition to the name of the command, the command may be called using one of these aliases.
func (Command) Description ¶
Description returns the description of the command. The description is shown in the /help list, and provides information on the functionality of a command.
func (Command) Execute ¶
Execute executes the Command as a source with the args passed. The args are parsed assuming they do not start with the command name. Execute will attempt to parse and execute one Runnable at a time. If one of the Runnable was able to parse args correctly, it will be executed and no more Runnables will be attempted to be run. If parsing of all Runnables was unsuccessful, a command output with an error message is sent to the Source passed, and the Run method of the Runnables are not called. The Source passed must not be nil. The method will panic if a nil Source is passed.
func (Command) Name ¶
Name returns the name of the command. The name is guaranteed to be lowercase and will never have spaces in it. This name is used to call the command, and is shown in the /help list.
func (Command) Params ¶
Params returns a list of all parameters of the runnables. No assumptions should be done on the values that they hold: Only the types are guaranteed to be consistent.
func (Command) Runnables ¶ added in v0.4.1
Runnables returns a map of all Runnable implementations of the Command that a Source can execute.
type Enum ¶
type Enum interface {
// Type returns the type of the enum. This type shows up client-side in the command usage, in the spot
// where parameter types otherwise are.
// Type names returned are used as an identifier for this enum type. Different Enum implementations must
// return a different string in the Type method.
Type() string
// Options should return a list of options that show up on the client side. The command will ensure that
// the argument passed to the enum parameter will be equal to one of these options. The provided Source
// can also be used to change the enums for each player.
Options(source Source) []string
}
Enum is an interface for enum-type parameters. Users may have types as command parameters that implement this parameter in order to allow a specific set of options only. Enum implementations must be of the type string, for example:
type GameMode string
func (GameMode) Type() string { return "GameMode" }
func (GameMode) Options(Source) []string { return []string{"survival", "creative"} }
Their values will then automatically be set to whichever option returned in Enum.Options is selected by the user.
type Line ¶
type Line struct {
// contains filtered or unexported fields
}
Line represents a command line holding command arguments that were passed upon the execution of the command. It is a convenience wrapper around a string slice.
func (*Line) Next ¶
Next reads the next argument from the command line and returns it. If there were no more arguments to consume, false is returned.
func (*Line) NextN ¶
NextN reads the next N arguments from the command line and returns them. If there were not enough arguments (n arguments), false is returned.
func (*Line) RemoveNext ¶
func (line *Line) RemoveNext()
RemoveNext consumes the next argument from the command line.
type NamedTarget ¶ added in v0.8.7
type NamedTarget interface {
Target
// Name returns a name of the Target. Note that this name needs not to be and is not unique for a Target.
Name() string
}
NamedTarget is a Target that has a name.
type Optional ¶ added in v0.7.0
type Optional[T any] struct { // contains filtered or unexported fields }
Optional is an argument type that may be used to make any of the available parameter types optional. Optional command parameters may only occur at the end of the Runnable struct. No non-optional parameter is allowed after an optional parameter.
type Output ¶
type Output struct {
// contains filtered or unexported fields
}
Output holds the output of a command execution. It holds success messages and error messages, which the source of a command execution gets sent.
func (*Output) ErrorCount ¶
ErrorCount returns the count of errors that the command output has.
func (*Output) Errors ¶
Errors returns a list of all errors added to the command output. Usually only one error message is set: After one error message, execution of a command typically terminates.
func (*Output) MessageCount ¶
MessageCount returns the count of (success) messages that the command output has.
func (*Output) Messages ¶
Messages returns a list of all messages added to the command output. The amount of messages present depends on the command called.
type ParamInfo ¶
ParamInfo holds the information of a parameter in a Runnable. Information of a parameter may be obtained by calling Command.Params().
type Parameter ¶
type Parameter interface {
// Parse takes an arbitrary amount of arguments from the command Line passed and parses it, so that it can
// store it to value v. If the arguments cannot be parsed from the Line, an error should be returned.
Parse(line *Line, v reflect.Value) error
// Type returns the type of the parameter. It will show up in the usage of the command, and, if one of the
// known type names, will also show up client-side.
Type() string
}
Parameter is an interface for a generic parameters. Users may have types as command parameters that implement this parameter.
type Runnable ¶
type Runnable interface {
// Run runs the Command, using the arguments passed to the Command. The source is passed to the method,
// which is the source of the execution of the Command, and the output is passed, to which messages may be
// added which get sent to the source.
Run(src Source, o *Output)
}
Runnable represents a Command that may be run by a Command source. The Command must be a struct type and its fields represent the parameters of the Command. When the Run method is called, these fields are set and may be used for behaviour in the Command. Fields unexported or ignored using the `cmd:"-"` struct tag (see below) have their values copied but retained. A Runnable may have exported fields only of the following types: int8, int16, int32, int64, int, uint8, uint16, uint32, uint64, uint, float32, float64, string, bool, mgl64.Vec3, Varargs, []Target, cmd.SubCommand, Optional[T] (to make a parameter optional), or a type that implements the cmd.Parameter or cmd.Enum interface. cmd.Enum implementations must be of the type string. Fields in the Runnable struct may have `cmd:` struct tag to specify the name and suffix of a parameter as such:
type T struct {
Param int `cmd:"name,suffix"`
}
If no name is set, the field name is used. Additionally, the name as specified in the struct tag may be '-' to make the parser ignore the field. In this case, the field does not have to be of one of the types above.
type Source ¶
type Source interface {
Target
// SendCommandOutput sends a command output to the source. The way the output is applied, depends on what
// kind of source it is.
// SendCommandOutput is called by a Command automatically after being run.
SendCommandOutput(o *Output)
// World returns the world that the Source is in.
World() *world.World
}
Source represents a source of a command execution. Commands may limit the sources that can run them by implementing the Allower interface. Source implements Target. A Source must always be able to target itself.
type SubCommand ¶
type SubCommand struct{}
SubCommand represents a subcommand that may be added as a static value that must be written. Adding multiple Runnable implementations to the command in New with different SubCommand fields as the first parameter allows for commands with subcommands.
type Target ¶
type Target interface {
// Position returns the position of the Target as an mgl64.Vec3.
Position() mgl64.Vec3
}
Target represents the target of a command. A []Target may be used as command parameter types to allow passing targets to the command.
type TargetFunc ¶
type TargetFunc func(src Source) (entities []Target, players []NamedTarget)
TargetFunc is a function used to find Targets eligible for a command executed by a given Source. Multiple functions may be added by using AddTargetFunc.
Source Files