There is a charter somewhere that states all tutorial series must start with the ubiquitous Hello World tutorial, and who am I to break the charter? So that is exactly what we are going to do here, a simple Hello World. This is as much about getting up and running with PS Studio than it is about C# coding, as there are a couple small gotchas. By the end of this tutorial you should be able to create, configure and run an application. In future tutorials, I will assume you have these abilities.
If you haven’t already, download and install PlayStation®Suite SDK from here. The install is pretty straight forward, take the defaults, next next next, done. If you want some idea of what you just installed check out this post. Now fire up PssStudio from your start menu. Once loaded, select File->New-Solution, like this:
In the “New Solution” dialog, on the left hand side expand C# then select PlayStation Suite. Select PlayStation Suite Application on the right, then fill in whatever name you want ( I am using HelloWorld ). This should automatically fill in Solution Name, it is your choice if you want to create a subdirectory or not, in this case I will. Fill out the dialog like this:
Click OK, and your solution will be created. Now we need to add an app.cfg file to your application, or it will fail to run. Note, this is not that same as a .NET application configuration file. In the Solution Explorer, right click your project name ( HelloWorld in my case ), then select Add->New File… like such:
Choose Misc on the left, then Empty Text File, name it app.cfg and click New.
The newly created file will open in the text editor, fill it in with the following:
resource_heap_size : 16384
managed_heap_size : 16384
gamepad : false
touch : false
motion : false
This file is telling what kind of machine your application is targeting. If you forget this step, the simulator pss.exe will just max out a CPU core, never responding. Now in the Solution panel, locate and double click AppMain.cs, this is where our application code will reside.
The actual process of doing Hello World on Vita is actually incredibly involved, as you need to do almost everything yourself. In this example however, I am going to take advantage of GameEngine2D, which is an included 2D Game engine that makes many of the drudge worthy tasks much easier. That means we need to add a reference to GameEngine2D. Adding a reference is simply saying “I am going to use the code included in this library” In order to add a reference to GameEngine2D, right click on References and choose Edit References… like such:
Then a dialog will pop up, locate Sce.Pss.HighLevel.GameEngine2D and check the box to it’s left. Then click OK.
Now we can add a using entry to tell our code to use the newly referenced library. This is where we run into a bug in MonoDevelop ( PS Studio ). Look at the following auto-completion screenshot:
Hmmm… where is HighLevel? We added the reference, it should be there. Well, on adding a new reference it seems the intellisense/auto-completion isn’t updated properly. I live by auto-complete so this is a big deal to me. Simply close and re-open your solution and presto:
Thankfully, you don’t really need to add references all that often, so while it’s inconvenient to have to exit and restart, its not the end of the world. PS Studio loads quickly enough to barely notice.
Alright, finally time for the code!
public class AppMain
public static void Main (string args)
Scene scene = new Scene();
var width = Director.Instance.GL.Context.GetViewport().Width;
var height = Director.Instance.GL.Context.GetViewport().Height;
Image img = new Image(ImageMode.Rgba, new ImageSize(width,height),
Texture2D texture = new Texture2D(width,height,false,
TextureInfo ti = new TextureInfo();
ti.Texture = texture;
SpriteUV sprite = new SpriteUV();
sprite.TextureInfo = ti;
sprite.Quad.S = ti.TextureSizef;
sprite.Position = scene.Camera.CalcBounds().Center;
PHEW! Pretty long for a Hello World eh? Truth of the matter is, had I not used GameEngine2D it would have easily been 4 or 5 times longer! We will cover what is going on behind the scenes ( the stuff GameEngine2D is handling ) in a later post. For now, just assume this is the way it works, at least while you are getting started. Now lets take a quick walk through the code and look at what’s happening here.
First we add our additional includes, Sce.Pss.HighLevel.GameEngine2D and Sce.Pss.HighLevel.GameEngine2D.Base. Our app consists of a single method, Main, as the event loop is actually managed by the Director.
Speaking of which, that is what the first line does, initializes the Director singleton. A singleton is a globally available object that is allocated on it’s first use. Director is the heart of your game, even though most of the complexity is hidden away. Remember, you have full source code for GameEngine2D available if you want to peek behind the curtain.
Next up we create a Scene. Again, Scene is an abstraction provided by GameEngine2D which can be thought of as a collection of visible “stuff”, the bits and pieces that compose what we want to display to the user and the Camera used to display them. We then call SetViewFromViewport() which creates a camera sized to the window. Generally without GameEngine2D, you would have to do this yourself, setting up an orthographic project.
The next two lines get the width and height, as reported by the Director’s OpenGL context. We then create an Image the same dimensions as our viewport. The Image class is used to hold binary image data, such as from a PNG or JPG file, but in this case we are create a new blank image. Once we create our Image, we call it’s DrawText method to draw our “Hello World” message. ImageColor represents the color we want to draw the image ( red in this case ), Font represents the font to draw the text in ( there aren’t really many options here ), while ImagePosition represents the location within the image to draw the text at.
Now that we have created an image, we need to create a texture out of it. Textures are most often thought of as the images mapped around 3D objects and in a way, that is still what we are doing here. GPUs have no concept of image files or pixels, they deal only with textures. That is why we copy our image data into the texture, using the SetPixels method of Texture2D and the ToBuffer() method of Image, to turn the images pixel data into an array Texture2D can use. At this point we are done with our Image, so we Dispose() it.
We next create a TextureInfo object and assign our newly created Texture to it. TextureInfo caches UV location information about the texture, as well as taking ownership of the texture itself. More importantly, it’s a TextureInfo object that Sprite expects, so that is what we create. Speaking of sprite, that is what we create next in the form of a SpriteUV.
Since modern GPUs don’t really deal with pixels anymore, everything is pretty much made out of textured polygons and SpriteUV is no exception. It is essentially a rectangular polygon that faces the camera with our image textured on it, all sprites are. Next up we set the sprite’s Quad ( the rectangle the texture is plastered to ) to be equal to the size of our texture, which in this case is the same size as our view. We now position our sprite smack in the middle of the view.
Now that we created our Image data, copied that image data into a Texture2D that was then assigned to a TextureInfo object, which in turn was assigned to a SpriteUV, we are now ready to add that fully textured sprite to our scene, which we do by calling AddChild(). Yeah, it sounds very convoluted, but you will find it natural very soon and generally you just load your textures from file anyways, greatly simplifying this process.
Anyways, now that we have our scene populated with our texture, which is the same size as the screen, we go ahead and tell the Director to do it’s thing, via RunWithScene(). You can think of this as the game loop, although the internals of what it’s doing are hidden from you.
Don’t worry, it’s really not as complicated as it seems. Now lets take a look at the fruits of our labour. To run it in PS Studio, select the Run menu and either choose Start Without Debugging or Start Debugging, depending if you want to be able to debug or not, like such:
And presto, all our hard work resulted in…
May not be much to look at, but you successfully created a game you can run on a Vita!
Speaking of which, if you need details of running on an actual device instead of in the simulator, read this post.
The complete project file for this tutorial are available for download here.