Opi Console Manual

This manual is not currently complete and there may be sections missing, if you have any particular questions please post them on the discussion section so that I know what is a more important topic to cover first.

Contents

  1. Quick Start
  2. Basic Features
    1. In-Built Commands
      1. CLS
      2. CVar
        1. Get Value
        2. Set Value
      3. Help
      4. Quit
    2. Parsing
      1. Simple String to Integer
      2. Simple String to Vector3
      3. Command Arguments to Colour
    3. Custom Commands & CVars
      1. Create Custom Command
      2. Register Custom Command
      3. Create Custom CVars
      4. Register Custom CVars
      5. Usage Levels
  3. Design Features
    1. Fonts
      1. Face
      2. Colour
    2. Background Colour
  4. Advanced Features
    1. Accessing CVars From Code
    2. RestartedDevice

Quick Start

Please read our Getting Started for the quickest way to get going with this console.

Basic Features

In-Built Commands

CLS
This command will be familiar to those who have used many other types of consoles, CLS stands for clear screen and it does what it says, it will remove any lines that are currently in the console (not from the log however) so that you can have a nice fresh console without restarting.
CVar
This command enables you to edit and get the values of CVars some examples of usage are as follows.
Get Value
cvar screenWidth
>> Cvar screenWidth value: 1024 usage: <int> (default: 800)
Set Value
cvar screenHeight 768
Help
This is a simple help command and will print out the usage for commands.

help cls
Quit
This command that takes no inputs, it simply tells your XNA game to quit as soon as possible.

Parsing

Because the console is working with strings a lot of the time you will often need to convert from the strings to other variable types, for this reason I have created a parser class which will allow you to easily and quickly parse from strings to many other variable types such as ints, floats and vector3's.

The parser features many ways of inputting the strings, from a simple string input to using the arguments that are outputted at a commands invoke function below you can see how to use a number of the parsing functions available to you with OpiConsole.
Simple String to Integer
This is as simple as it gets, the integer is just parsed straight from the String to the integer and returned as the result for i.
string str = "1";
int i = Parser.toInt(str);
Simple String to Vector3
This is again quite simple the only difference here is that we're accepting 3 inputs within the string and outputting the result.
string str = "1.1 2.2 3.3";
Vector3 vec = Parser.toVector3(str);
Command Arguments to Colour
Here we have one of the more advanced parsing techniques, this time we give all the arguments to the parser and tell it which index of the arguments is the first variable within the Colour element we want to parse, we also tell it that we are looking to take in an alpha value too.
public override bool Invoke(List<string> args)
{
     if (args.Count == 4)
     {
          Color c = Parser.toColour(args,0,true);
          return true;
     }

     return false;
}

Custom Commands

OpiConsole allows you to create your own commands, these can carry out any functions when they are invoked and can take any number of inputs.

Create Custom Command

To create a custom command you need to create a class which inherits the Command class along with an override of the invoke function, below you can see a basic command which adds two numbers together, you'll notice that you must supply a Usage Level, this defines the level of user that you need to be in order to run this command.

    public class Command_Add : Command
    {
        public Command_Add()
            : base("add", "Adds two numbers (Usage: a b)", UsageLevel.NORMAL)
        {
        }

        public override bool Invoke(List<string> args)
        {
            if (args.Count == 2)
            {
                int output = Parser.toInt(args[0]) + Parser.toInt(args[1]);
                console.Print("Answer: " + output.ToString());
                return true;
            }

            return false;
        }
    }

Register Custom Command

Registering commands is rather simple and only requires one line of code, you simple create an instance of the custom command and use the RegisterCommand function.

//Register a custom command to the console
console.RegisterCommand(new Command_Add());

Create Custom CVars

To create a custom cvar you need to create a class which inherits the CVar class and the invoke function, this invoke function requires that you call the setValue() method (without it your cvar will never be updated). The invoke function allows you to check that the input is valid as well as perform any extra functions that might be required for this cvar, below is an example of a custom cvar.

    public class CVar_Language : CVar
    {
        public CVar_Language() : base("Language", "English", CVarType.STRING, UsageLevel.NORMAL, true) { }

        public override bool Invoke(List<string> args)
        {
            if (args.Count < 1 || args.Count > 1)
                return false;

            //Set the value of the CVar
            return setValue(args);
        }
    }

Register Custom CVars

Registering custom cvars is similar to registering custom commands, once again you are only required to write one line which creates an instance of the custom cvar class and passes it to the RegisterCVar function.

//Register a custom cvar to the console
console.RegisterCVar(new CVar_Language());

Usage Levels

OpiConsole includes a hierarchy permission system which allows you to create commands that only certain users will be able to use, there are currently four usage levels which are listed below.
  • NONE
  • DEBUGDEV
  • DEV
  • NORMAL

OpiConsole defaults to using the NORMAL usage level which means that only commands marked as NORMAL will be usable, if you wish to use other commands then please set the consoles user level with a higher usage level. An example would be to set the user level to DEV which will allow you access to all commands set as DEV as well as those set as NORMAL.

//Make sure we can see the debug too
console.UserLevel = UsageLevel.DEBUGDEV;

Design Features

In this section we'll be discussing the design features of the console, if your wanting to modify the console to blend more into your game then this will be the section for you.

Fonts

Fonts can be easily updated and changed on the fly within Opiconsole, allowing you to have a look more suited to your games theme.
Face
Changing the font that the console uses is rather simple and requires only one line of code.

console.Font = Content.Load<SpriteFont>("Materials/Fonts/Consolas_16pt");

Note: When choosing a font face I recommend using a monotype font so that the output is easier to read at a glance.
Colour
The console uses a number of different colours for the text, each output level has its own colour and each of these can be edited to a colour of your choosing. The following example shows how to edit all four visible console levels (the TXTFILE usage level is only outputted to the log on PCs).

console.SetTextColour(new Color(18, 150, 134), ConsoleLevel.DEBUG);
console.SetTextColour(new Color(25, 87, 62), ConsoleLevel.NORM);
console.SetTextColour(new Color(164, 171, 82), ConsoleLevel.WARN);
console.SetTextColour(new Color(255, 0, 0), ConsoleLevel.WARN);

Background Colour

You can also edit the colour of the rectangle that the console draws to, this rectangle uses the alpha component so make sure you supply the alpha if you want to show elements underneath the console.

console.BackgroundColour = new Color(0,0,0,100);

Advanced Features

Accessing CVars From Code

The values set within your custom cvars can be accessed from anywhere within your source code that can access the console, the below code shows how to extract the language cvar created in the example issued with OpiConsole.

console.Print("Language is currently: " + console.GetCVar("language").ToString());

RestartedDevice

This function tells the console that the screen resolution has changed and that it should update the size of the window, this function is NOT automatically called (I haven't found a way to detect that the screen resolution has changed yet) therefore you must call this function every time you change the screen resolution during runtime. The code below shows an example of what you should do.

graphics.PreferredBackBufferWidth = 1280;
graphics.PreferredBackBufferHeight = 800;
graphics.ApplyChanges();
console.RestartedDevice();

Last edited Feb 15, 2010 at 7:54 PM by opdude, version 10

Comments

No comments yet.