Tutorial Part 2: Player Creation and Display

Creating a Player Entity

Important note: These tutorials were written for SadConsole version 7.x. The version 8.x tutorials are here.

Let’s get a player on the screen. This means introducing a new SadConsole class called Entities. Entities are objects that have an X and Y position on a console, a name, and – this is for much later – an animation. An Entity can be something as simple as a single dot on the screen, or a complex animated creature. Let’s try the single dot first.

In this tutorial we’ll create an Entity (our Player’s character), and display it on the screen.

Start by declaring a new Entity belonging to your Program class. Variable declarations belong between the Class definition and class methods.

class Program
    {
        public const int Width = 80;
        public const int Height = 25;
        private static SadConsole.Entities.Entity player;

This declaration says to the compiler: ‘Make some space for a new variable called player whose type is Entity. We don’t know what exact data is going to go inside of it, but we know the type of data that will.’

The “private” declares this as a private variable, meaning that only methods in the Program class can see it. No other class is allowed to peek into Program’s private data. We’ll talk about public variables later. The “static” keyword tells the compiler that we plan on making a single copy of player, not a hundred instances of it. We’ll talk about instancing later. For now, just accept that it needs to be a static variable.

Now let’s create a new method that creates or “instantiates” the player variable by filling it with some basic data that describes its position and name.

Create a new method below the Init() method that looks like this:

        // Create a player using SadConsole's Entity class
        private static void CreatePlayer()
        {
            player = new SadConsole.Entities.Entity(1, 1);
            player.Animation.CurrentFrame[0].Glyph = '@';
        }

A private method is one that only this class (Program) has access to. No other class is able to call CreatePlayer() except Program. Void is the “return type” of this class. A return is a final value that a method spits out when it finishes running. A method that returns a void basically says to the compiler: I don’t care about what the final output of this method is, I just want the method to run and do its thing.

And again, this is a static method because there can only be one instance of it. There’s a Highlander joke there somewhere. We’ll talk about that much later in the tutorial.

Instances and Classes

The meat of this method is to “instantiate” player… in other words, turning an empty variable into an “instance”. In Object-Oriented Programming, our goal is to create a general framework of something, and then create specific instances of it. So if your goal is to create a cat, you’ll write a class called Cat that has a few general properties: a colour, a first and last name, four legs, a head, a meow, whiskers, a tail…. That framework or class only tells us what Cats generally are like. It’s up to us to create a specific instance of a cat:

MyCat : Cat

MyCat is an instance of Cat. There are a kazillion instances of Cat all with different colours and features, but only one general class of Cat.

That’s what we’re doing here with an Entity. We’ve got a general framework of Entity that we’re populating with some specific data… and in the process we’re making a new Entity called player.

player = new SadConsole.Entities.Entity(1, 1);

The “new” keyword tells the compiler that we want to create a new instance of an existing class called Entity. The (1,1) are parameters passed to the Entity class’s constructor.. these tell the constructor to create an Entity of a certain kind. In this case, 1 and 1 refer to the Width and Height of the Entity… meaning that it will be 1 character wide and 1 character tall. The Entity constructor can accept many kinds of parameters, like Animation data, font type, and so on. For now, let’s stick with a Player character that’s sized 1×1.

Entity Properties

player.Animation.CurrentFrame[0].Glyph = '@';

The above code updates a single animation frame of the player Entity. Remember how I said all Entities can have Animations earlier? The animation’s “Glyph” property tells SadConsole what ASCII character or graphics tile we should display onscreen for the Entity. Let’s stick with ASCII characters to make our lives a little easier for now, but rest assured – it’s just as easy to use graphics tiles to represent each Entity on the screen. The CurrentFrame[0] property just tells SadConsole that we’re trying to modify the 0th or “first” frame of the animation. Remember: computers start counting at zero, not at one! 🙂

Now that we’ve created the method to create the player, we have to actually call the method from somewhere in our code. A method alone doesn’t do anything unless it has been called by another method. So let’s insert some code at the end of the Init() method:

        private static void Init()
        {
            // Any custom loading and prep. We will use a sample console for now

            Console startingConsole = new Console(Width, Height);
            //startingConsole.FillWithRandomGarbage();
            startingConsole.Fill(new Rectangle(3, 3, 27, 5), null, Color.Black, 0, SpriteEffects.None);
            startingConsole.Print(6, 5, "Hello from SadConsole", ColorAnsi.CyanBright);

            // Set our new console as the thing to render and process
            SadConsole.Global.CurrentScreen = startingConsole;
            
            //create an instance of the player
            CreatePlayer();

            // add the player Entity to our only console
            // so it will display on screen
            startingConsole.Children.Add(player);
        }

While you’re there, why not comment out FillWithRandomGarbage()? Now that we’re getting down to business, we don’t need our console covered with garbage anymore 🙂

CreatePlayer() runs the method that we wrote earlier.

Console.Children.Add

startingConsole.Children.Add() is one of the most important methods in SadConsole. Think of a Console as a blank canvas that can have many things stuck on to it. To stick something on to a console – and have the ability to pull it off the console later, you need to Add it as a Child of the console. That’s so the console can keep track of what has been added or removed. Every console can act like a parent to other entities, and even other consoles! Think of your e-mail client. It’s a window, and it has other windows nested inside of it like individual e-mails and the composer. That’s how consoles work too.

So if you forget to add an Entity to your console, SadConsole won’t draw it! Whenever you run into a situation where you’re seeing a black screen and expected to see graphics on it – it’s likely because somewhere along the way you forgot to add a graphics element to a parent Console. This probably seems confusing for now, but Parent-Child relationships between consoles, other consoles, and entities, will become an extremely useful concept later in this tutorial when we start building our own graphical user interfaces.

So go ahead and run your project. You should have a little white @ symbol doing a whole lotta nothin in the top left corner of the window.

Entity Customization

Now let’s customize our little player character for fun by adding some code to CreatePlayer():

        // Create a player using SadConsole's Entity class
        private static void CreatePlayer()
        {
            player = new SadConsole.Entities.Entity(1, 1);
            player.Animation.CurrentFrame[0].Glyph = '@';
            player.Animation.CurrentFrame[0].Foreground = Color.HotPink;
            player.Position = new Point(20, 10);
        }

The .Foreground property allows you to change an ASCII Glyph’s colour on the fly. Color is a Microsoft XNA class that gives you access to a predefined table of colours, which I’ve found really useful. Try changing HotPink to any of the colours you see in the list.

the .Position property sets the X and Y coordinates of the Entity on the console. You’ll notice that we set both the X and Y coordinates at the same time using a new variable type called “Point”. A Point consists of two integer coordinates (e.g. if this were a piratey treasure map, a Point on it would be at: Latitude 60, Longitude 20). We use the “new” keyword to tell the compiler to create a new variable of type Point with 20 and 10 as its coordinates.

Download the final program-example.cs file for this tutorial here.

Run your program. You can move the player’s character anywhere you’d like on the screen by changing the values in the Point() statement. In our next tutorial, we’ll work on moving the character around using the keyboard in real-time instead.

Published on October 26, 2018