tylog

Spark

2021-12-06T00:00:00+00:00

The Game

Set in the world Innis Fhaolain, guide the fairy Alette as she helps a village of grumpy gnomes. Discover why a gloom has been cast over the town, use Alette’s spark to solve puzzles unlocking more of the island, bring peace and joy to the citizens, and resolve Alette’s own troubled heart.

Can you solve all the NPC puzzles? Can you find all the hidden items in the world that can be transformed by a little spark?

Be the hope of gnomies everywhere! Shine your light and be the Spark of change!

A HomeTeam GameDev project!

A Javascript puzzle game.

My Contribution

Core gameplay, project lead, AI behaviors, main artist, primary writer, tutorial, UI framework and primitives, performance optimizations, environment design, building/furniture art, NPC and object interactions, pathfinding, fairy/gnome sprites, custom editor, particles, input handling, asset management, hints system

Play

This game was developed by members of the HomeTeam Gamedev club, myself included. Find out more about the club, or play this game: Play on itch.io

Media

An Intro to JS Particles, Pt. 1

2021-01-20T00:00:00+00:00

About

This article will describe how you can implement a particle system in pure/vanilla javascript for use in web/html games or other web-based/browser projects.

Meet Pete

So Pete the Particle is a happy little particle running in the canvas shown above. Feel free to poke him if he isn’t showing up very well. But you may be wondering… What exactly is a particle and why would I want to implement my own? First, in my perspective at least, a particle is simply a procedurally-generated visual effect that can be added to a game (or any other visual project). Think of a shower of sparks when you shoot an enemy, a trail of dust that kicks up when your character runs, even footsteps that your character may leave in sand or snow. These can all be implemented through particles. And while there are other ways to implement visual effects, I’ll present you some advantages to using a particle system, which allows you to fire and forget visual effects so that your game logic doesn’t need to keep track of animation or effect state.

Game Hooks

Let’s take a closer look at Pete and how Pete is integrated into the game loop. To understand how the particle logic works, we need to understand how it will be hooked into your game. The game model I’m using here assumes that all logic is tied to Animation Frames. In each frame, you are making updates to your game model and then rendering out the results to display in your browser. The particle logic will follow this same model.

I’ll assume that your game loop looks something like this:

var lastUpdate = performance.now();
const maxDeltaTime = 100;
const updateCtx = { deltaTime: 0 };
const canvas = document.getElementById("canvas");
const renderCtx = canvas.getContext("2d");
function loop(hts) {
    updateCtx.deltaTime = Math.min(maxDeltaTime, hts - lastUpdate);
    lastUpdate = hts;
    update(updateCtx);
    render(renderCtx);
    loopID = window.requestAnimationFrame(loop);
}

Where update(updateCtx) and render(renderCtx) are your entry points to your game logic. We’ll use these same entry points for operations on particles. While you could get away with a single function call, there’s reasons breaking them out makes sense. Specifically there may be cases where you want to update the state of particles (e.g.: position and such), but don’t want to render it (e.g.: offscreen or not visible). Also note that I’m passing in a few variables which will be important to particle operations. updateCtx is an object that contains a deltaTime attribute, and renderCtx is the canvas context onto which stuff will be rendered. We’ll see how these are used when we dive deeper into what makes Pete tick. Let’s assume that your main update and render methods have been updated to call the particle’s entry points, as shown here:

const pete = new PeteParticle();
update(updateCtx) {
    ...
    pete.update(updateCtx);
    ...
}
render(renderCtx) {
    ...
    pete.render(renderCtx);
    ...
}

Particle Logic

To implement Pete, we are going to introduce a class to store some data and define the game hooks to allow updates and rendering of the particle. What data is needed to model the behaviour we are seeing? Well, there’s a position on the screen to start with (let’s call that x,y coordinates), and the shape of the particle, which is a filled circle which can simply be represented by a radius (size) as well as a color associated with the particle (color). Those are all static properties, but what about the behaviour? Well, the particle is moving. There’s lots of ways we could represent that, but the easiest is to just consider the change of position based on x and y axis over time. Let’s call the change in x, delta X and the change in y, delta Y (dx and dy for short). Finally, when the particle hits the edge of the canvas it changes direction. We need some logic to keep track of the bounds of the canvas. This can be represented by a minimum and maximum x value (minx, maxx) and same for a y value (miny, maxy). Putting that into a class structure and initializing looks like:

class PeteParticle {
    constructor(spec={}) {
        // current position
        this.x = spec.x || 0;
        this.y = spec.y || 0;
        // deltas for x,y - represents velocity in pixels per second
        this.dx = (spec.dx || 50) * .001;
        this.dy = (spec.dy || 50) * .001;
        // size of particle
        this.size = spec.size || 5;
        // color of particle
        this.color = spec.color || "red";
        // bounds
        this.minx = spec.minx || 0;
        this.miny = spec.miny || 0;
        this.maxx = spec.maxx || 400;
        this.maxy = spec.maxy || 400;
    }
}

Two notes here:

I like to use spec objects in constructors. It allows you to easily change the calling parameters for object creation (which we will do later) as well as allows you a way to easily specify defaults for object creation, which I’ve done here (spec.x || 0 becomes undefined || 0 which becomes 0 when spec.x is undefined). So you can make a PeteParticle just by calling new PeteParticle() and you will get something that works.
You’ll note a .001 multipled to the dx and dy values. If you look back at the game loop, the deltaTime attribute being passed to the update function is computed in milliseconds. I like to think of velocity in terms of pixels per second, so to get to pixels per millisecond, multiply by .001.

Now that we have data, let’s take a closer look at the update and render methods that are needed to get Pete moving and rendering. If you remember, update is being passed a context that includes a deltaTime attribute which represents the amount of time in milliseconds since the last update was called. This is the elapsed time since we’ve last made any changes to Pete. In the data for Pete, we expressed movement by keeping track of a delta x and y which represented the number of pixels of movement per unit time (millisecond in our case, remembering we converted dx and dy in seconds by multiplying by .001 converting to milliseconds). So to get how far Pete should have traveled since the last update, all we need to do is multiply the dx and dy values by deltaTime and then store the results. Take a look:

update(updateCtx) {
    let dt = updateCtx.deltaTime;
    // update position
    this.x += Math.round((this.dx * dt));
    this.y += Math.round((this.dy * dt));
}

Pretty simple right? Note: I’m rounding the change in position I’m adding to x and y as a best practice to keep x and y as integers. Floats work too, but are a bit more computationally heavy when rendering. This is enough to get Pete moving, but Pete would quickly become lost as he wanders off the screen we’ve provided. To keep Pete safe (and always visible) we’re going to add a fence that tells Pete how far he can go in any direction. If he goes to far in any direction, we’ll tell him to turn around and go in the opposite direction at the same speed. From our data model for Pete the fence was represented by the minx, miny, maxx, maxy variables. Let’s take a look at how to implement the fence:

update(updateCtx) {
    let dt = updateCtx.deltaTime;
    // update position
    this.x += Math.round((this.dx * dt));
    this.y += Math.round((this.dy * dt));
    // update direction
    if (this.x <= this.minx) this.dx = Math.abs(this.dx);
    if (this.y <= this.miny) this.dy = Math.abs(this.dy);
    if (this.x >= this.maxx) this.dx = -(Math.abs(this.dx));
    if (this.y >= this.maxy) this.dy = -(Math.abs(this.dy));
}

The logic for the fence is pretty straightforward. If Pete’s position ever drops below a minimum or above a maximum, we change the corresponding position delta to be negative or positive to turn Pete around. Implementation Note: using Math.abs is required here vs. just flipping the sign of the delta (e.g.: this.dx = -this.dx). Remember that the delta time passed in is variable as it is the actual milliseconds since last call. For example, say your dx is -5 and current x position is 5 and you are passed a deltaTime of 10. Your new position would be calculated as this.x += -5*10 or this.x = 5 - 50 or this.x = -45. Assuming our minx is 0, -45 is well under this, so we would swap the sign of dx which would now be 5. Now say the next frame’s deltaTime is 5. Using the same computation, this.x += 5*5 or this.x = -45 + 25 or this.x = -20. Uh oh… this is still below our minumum minx, so if we were just swapping the sign, we would send the particle back in the wrong direction. I actually had this bug when I first implemented ;p.

Final step is to figure how to actually draw Pete. Using Javascript primitives, this is actually pretty easy. Pete is just a filled circle with a specific color, so we’ll use the Arc primitive:

render(renderCtx) {
    renderCtx.beginPath();
    renderCtx.arc(this.x, this.y, this.size, 0, Math.PI*2);
    renderCtx.fillStyle = this.color;
    renderCtx.fill();
}

Let’s break this down. First renderCtx.beginPath() (reference: BeginPath) is used to start a new rendering path in Javascript. Rendering paths in Javascript allow you to build out a shape using multiple primitives (like lines, arcs, rectangles, etc) before doing a single render/draw call for the entire path you’ve laid out. Here, we’re only using a single primitive, so it doesn’t buy us much, but is still needed to setup our render state. renderCtx.arc(this.x, this.y, this.size, 0, Math.PI*2) is where we are telling Javascript to draw our filled circle. We pass in Pete’s position using this.x, this.y, this.size is the radius of the circle (in pixels) which we set in our constructor, and the 0, MathPI*2 is used to identify the start and end angles (in radians) of the arc to draw (0 to 2*PI is a full circle). renderCtx.fillstyle = this.color is used to set the color of the circle (reference: FillStyle), which can be named colors like red or black, RGB hex values like #808080 for a gray, or a RGB color string like rgb(127,127,127) (reference: CSS Color Value). And finally, the renderCtx.fill() call renders the path, our circle, to the canvas (reference: Fill).

Putting It Together

The last piece of the puzzle is the initialization code for Pete. You’ll note that in the first introduction to Pete and the canvas below, Pete starts at a random location and heads off in a random direction and a fixed speed. We also need to define what the fence parameters should be. Let’s start with the fence, as it’s easiest. We will set Pete’s boundaries to simply be the boundaries of the canvas we are using. So spec = { minx: 0, miny: 0, maxx: canvas.width, maxy: canvas.height } will do fine. Starting position also is easy. We’ll pick a random number between 0 and 1 (using Math.random()) and multiply by the canvas height and width, as that’s the bounds we are using for Pete. For handling movement in a random direction but at constant speed. I pick a speed, say 200 (measured in pixels per second), then pick a random angle. To get the x, y deltas, I simply use Math.sin(angle) and Math.cos(angle). Let’s put this all in a function:

function makePete() {
  let speed = 200;
  let angle = Math.random() * Math.PI * 2;  // angle is in radians, so full circle is PI * 2
  petes.push(
    new PeteParticle({
      x: Math.random() * width,             // random starting location
      y: Math.random() * height,
      dx: speed * Math.cos(angle),          // starting deltas/movement based on angle
      dy: speed * Math.sin(angle),
      color: "#A9BCD0",                     // picking a color
      maxx: width,                          // setting fence max values (min default to 0)
      maxy: height
    })
  );
}

By putting this in a function, we can now call it multiple times to get multiple particles, all following the same rules. The only thing we haven’t accounted for is keeping track of our Pete particles. In the above function there is a petes.push() call. I’m using an array named petes, allocated by using var petes = [];. So that will need to be declared prior to calling our makePete() function:

var petes = [];
for (let i=0; i<5; i++) {
    makePete();
}

This handles creating five Pete particles (yay, he now has friends!). But we need to update our update() and render() functions accordingly:

update(updateCtx) {
    for (const pete of petes) {
        pete.update(updateCtx);
    }
}
render(renderCtx) {
    for (const pete of petes) {
        pete.update(renderCtx);
    }
}

So now we have Pete and a couple of friends. Use the +friend button to add more.

I’ll stop here for now, as I ended up being long winded in explaining everything. And there’s still quite a bit of ground to cover. Hopefully I’ve outlined some basic concepts: a particle really is some data and rules for updating and rendering. Logic for initialization lies outside the particle and that we need to be able to hook to the main game loop. We still need to get to the “fire and forget” point I raised at the beginning of the article. And I still want to cover more on the creation and expiration of particles and ways to handle that. And while I’m sure Pete is a fine particle, there’s a lot more we can do and I’ll provide some more exciting examples. Look for these topics to be covered in more detail in coming posts.

The full code for this example is below, or you can play around with it for yourself using this CodePen.

var lastUpdate = performance.now();
const maxDeltaTime = 100;
const updateCtx = { deltaTime: 0 };
const canvas = document.getElementById("canvas");
canvas.width = window.innerWidth;
canvas.height = window.innerHeight;
const width = canvas.width;
const height = canvas.height;
const renderCtx = canvas.getContext("2d");
const petes = [];
function loop(hts) {
  updateCtx.deltaTime = Math.min(maxDeltaTime, hts - lastUpdate);
  lastUpdate = hts;
  update(updateCtx);
  render(renderCtx);
  window.requestAnimationFrame(loop);
}
function update(updateCtx) {
  for (const pete of petes) {
    pete.update(updateCtx);
  }
}

function render(renderCtx) {
  renderCtx.clearRect(0, 0, width, height);
  for (const pete of petes) {
    pete.render(renderCtx);
  }
}

window.requestAnimationFrame(loop);

class PeteParticle {
  constructor(spec = {}) {
    // current position
    this.x = spec.x || 0;
    this.y = spec.y || 0;
    // deltas for x,y - represents velocity in pixels per second
    this.dx = (spec.dx || 50) * 0.001;
    this.dy = (spec.dy || 50) * 0.001;
    // size of particle
    this.size = spec.size || 5;
    // color of particle
    this.color = spec.color || "red";
    // bounds
    this.minx = spec.minx || 0;
    this.miny = spec.miny || 0;
    this.maxx = spec.maxx || 400;
    this.maxy = spec.maxy || 400;
  }
  update(updateCtx) {
    let dt = updateCtx.deltaTime;
    // update position
    this.x += Math.round(this.dx * dt);
    this.y += Math.round(this.dy * dt);
    // update direction
    if (this.x <= this.minx) this.dx = Math.abs(this.dx);
    if (this.y <= this.miny) this.dy = Math.abs(this.dy);
    if (this.x >= this.maxx) this.dx = -Math.abs(this.dx);
    if (this.y >= this.maxy) this.dy = -Math.abs(this.dy);
  }

  render(renderCtx) {
    renderCtx.beginPath();
    renderCtx.arc(this.x, this.y, this.size, 0, Math.PI * 2);
    renderCtx.fillStyle = this.color;
    renderCtx.fill();
  }
}

function makePete() {
  if (petes.length >= 50) return;
  let speed = 200;
  let angle = Math.random() * Math.PI * 2;
  petes.push(
    new PeteParticle({
      x: Math.random() * width,
      y: Math.random() * height,
      dx: speed * Math.cos(angle),
      dy: speed * Math.sin(angle),
      color: "#A9BCD0",
      maxx: width,
      maxy: height
    })
  );
}

for (let i = 0; i < 25; i++) {
  makePete();
}

Witches and Guns

2020-12-06T00:00:00+00:00

The Game

A Javascript shooter with waves of enemies, bosses and multiple levels.

My Contribution

More Javascript and pixel art work and related game integration.

Room design and tile art (yard, kitchen, living room, laundry room), level grid implementation, tile layering, subtile support, animated tile support, fridge boss animations and taunts, ice cube animation integration, teapot animation, title screen and related transitions.

Play

This game was developed by members of the HomeTeam Gamedev club, myself included. Find out more about the club, or play this game: Play on itch.io

Media

Hard Glitch

2020-10-25T00:00:00+00:00

The Game

A rogue-like adventure cyber adventure set inside your computer. Help “Glitch” survive and escape the confines of the computer world. Solve puzzles and come up with a strategy to make it out alive.

My Contribution

Continued to build out my experience with Javascript games. First time building/working with a particle system in JS. First time building out a procedural wall and tile system.

Particle systems (glitch, trace, scan, portal, spawn, missile, color, spark, repair, wait, hex spin, lightning jump, fade, explosion swirl, blip edge pathing), procedural tile selection and wall generation, FX randomization, wall tiles art, decrypt/triangle animations, mock ups (tile bg, walls, void, experimentation with negative space/holes, perspective, color tests), color adjustments, moving wall v2, level design concepts art, floor art, NPC wait animation, warm and cool level themes, lots of asset and code cleanup, additional tile type rules, seam fix, take/drop animations, move animations, highlights art v2, laser walls, tile overlay, title screen background

Play

This game was developed by members of the HomeTeam Gamedev club, myself included. Find out more about the club, or play this game: Play on itch.io

Media

Falldale Extended Edition

2020-05-03T00:00:00+00:00

The Game

A role-playing action adventure game taking place in and around the medieval village of Falldale. Rid the village of the goblin threat. Uncover the truth behind the missing caravan. Help the Princess bring peace to the countryside once and for all.

My Contribution

My first real taste for both working on a Javascript game and working on pixel art.

Art (tables, bar stools, wooden walls, flagstones, bar joints, top wall updates, window, pine tree, cliffs, caves, bonfire animation, castle walls), level design (castle, east woods), Tiled integration, map data conversion, assorted bug fixes, collision system updates, new quest code features, AI zone support, orc boss AI improvements, hammer weapon, wizard area colliders, transitions, enemy placement & tuning

Play

This game was developed by members of the HomeTeam Gamedev club, myself included. Find out more about the club, or play this game: Play on itch.io

Media

TyTe Tile Level Editor

2020-04-02T00:00:00+00:00

Intro

OK. The world is a bit of a crazy place right now (thanks CoronaVirus). And like many folks, my family has been seeing a lot of each other over the past few weeks, and likely months to come. While we are truly going through some strange times, our outlook is good. Let’s use this time together to make something positive. So that’s our plan.

One of the ideas that we have had for a bit now, but really haven’t had the time for, is to come up with a video game that the entire family can work on together. Guess what, we have the time now… so, what we’ve basically came up with is a top-down adventure-style game, where the goal is to basically help others and make your world a better place. So, my family all has different talents… my oldest daughter likes work on art, my youngest is more of a planner/layout specialist, and my wife likes to develop stories (I guess that leaves me with coding).

As I’m trying to pull together how we can all contribute, I figured that level editing a top-down world would be one of those areas. I also figured that we would work with javascript as the development language, as it’s pretty easy to use (you have a browser, right?) and it’s something that I’ve been actively trying to learn as part of my HomeTeam GameDev club work. Given those constraints, I started looking at free software that’s already out there that we could use. And there are quite a few options. Top of the list is Tiled. This is a full-featured, actively-maintained and looks to be very efficient level editor. It supports all kinds of features, different kinds of maps, and integrations into GameDev engines. And it’s basically free. It seems like if you take the time to learn how to use the tool, it would be a great editor. However, one of my goals for our family project is for folks to be able to jump right in and help, without too much of a learning curve, or having to figure out how to use a tool.

So, with the idea of keeping things simple, I thought it would be a good idea to write a level editor from scratch using Unity. Ya, that sounds like a good idea…

Design

One of the direct benefits of writing your own tool is that you can build it to meet your exact needs. So lots of fancy features like supporting different map types or engine integrations aren’t needed. I’m making my game in javascript and I’m using a top-down set of tiles. This limits the required feature set:

Easy to use
Needs to directly edit the game files used in my javascript project (more on this below).
Support for multiple levels/zones
Support for multiple layers of tiles within a zone (e.g.: background, foreground, etc).
Basic editor functions, add tiles, flood fill, erase
Portable (can run on Mac/Windows)

My gamefiles are laid like so:

projectdir
├── index.html
├── ...
└── src
    ├── img
    │   ├── 32grass.png
    │   ├── 32road.png
    │   ├── sprites.json
    ├── js
    │   ├── ...
    └── zones
        ├── start.json
        └── test.json

The important folders here are the img and zones folders. First off, the img folder contains all of the individual sprite files that I intend to use in my game. I know lots of games use sprite sheets instead of individual images for a number of reasons. Maybe I’ll get there at some point, but for right now, it is easier for me to manage them in separate files. Within this folder is also a sprites.json file which I maintain. This contains the mapping between a unique identifier for the sprite (just an integer), and the sprite file itself. The unique identifier will be used and referenced in the saved level data. For now, I just manually edit this json file when I need to add more sprites. The biggest reason for this is that besides data needed for the level editor, I intend to add data specific to the game (like collision info, terrain info, etc.). Next is the zones folder. This is where I intend to keep all of my level/zone definitions. A zone definition consists of information about the zone, like it’s name, it’s dimensions, and the list of layers for that zone. Each layer has a name and the actual grid of tiles that have been assigned to that layer, referenced by the unique sprite identifiers (it’s an array of integers :)).

My design approach for the editor was driven by getting something running as soon as possible. Probably the biggest issue with this approach is that I ended up using individual game objects to represent the tiles within the grid to edit. You can do the math… let’s say you have a new zone you want to create that is 50x50 in dimensions. Let’s also say you want to have a background, a foreground, and a separate object layer. You now have 50x50x3=ouch game objects running in unity while you edit this zone. Now, I’ve been editing zones with multiple layers as big as 100x100 on my laptop. There is a little lag, but it works (my laptop just gets warm). So, it fits within the constraint of getting something working up and running ASAP. I do want to go back and change out the grid managemnt using a single canvas. It’s on my to-do list along with a handful (err… maybe more than that) of other things.

The rest of the code is pretty straight-forward and I’m overall happy with how it’s working. I won’t bore you with further details. The code is there for you to view or drop me a line if you have questions/comments.

Usage

See my README file in the github project for the level editor for how to use the tool.

References

TyTe on Github - The entire Unity project and all source code, with example levels/tile art.
TyJsJam on Github - An example JS game framework utilizing the levels/tiles managed by the editor.

Thanks

HomeTeam GameDev Folks - For support, inspiration, and bits and pieces of code from other JS games.
Austin Blackwood @AABlackwood - For the dragon tile used in the referenced projects.
Matiaan from OpenGameArt.Org - For the top-down tileset used in the example projects.

Utilizing Unity Packages for Reusable Code Chunks

2020-02-29T00:00:00+00:00

Intro

So, you find a good way to solve a particular problem while working on a project, and you write some code to handle it. It gets integrated into your project and everything works. Yay! Now if there’s one thing I’ve learned about Unity, it’s that there are tons of repeated patterns of problems. So, it’s not too hard of stretch to imagine that the problem that you faced and solved in project foo you will also find your new project bar. Common practice would say to just copy the code and be done with it. And for small snippets of code, that totally makes sense. For larger problems, well, maybe not so much.

As an example, a lot of my projects I’ve been working on lately make use of procedural meshes. So I’ve created some code to provide an easy-to-use interface for creating dynamic meshes and interface w/ Unity to translate to in-game objects. Over time, I’ve slowly added features to this code base to handle new use cases. The result is a self-contained set of functions and assets that I can use in a wide range of projects. And while I could technically copy this code from project to project, that ends up being quite a bit of overhead. I have things like unit tests, shaders and unity test scenes that I used to develop the set of mesh routines. I want to be able to treat this code as a single unit, and use it in whatever project I want, without that project worrying about the maintenance of the mesh code.

This tutorial will cover how I go about doing just that by utilizing Unity’s Custom Packages. While Unity packages can be used for a number of things, including models, textures, and other custom assets, this demo will show you how to setup custom packages for C# code assemblies. Allowing you to easily share common code across your Unity projects.

Basics

There’s a few assumptions that I’m going to make here:

You’re using Unity and have C# projects
You’re using git for version control
You have a single release branch (this demo just uses master)
You have code that is modular/self-contained and want to use it across multiple projects

For the purposes of this demo, I’ll be introducing three Unity projects that I’m using as packages:

tytest - A simple test framework for tests in Unity.
tymesh - A utility class for working with dynamic meshes
tysimpleshape - A utilily class that uses the tymesh package and introduces simple shape primitives.

Building a Unity Package

There’s a little setup and reorganization that’s needed to setup a Unity package. While there’s likely multiple ways of managing a Unity package, my requirement for my workflow is that I need to be able to manage each package as a complete Unity project. That way, if I need to make a change to a package script, I can test make that change locally in a full blown Unity project, make sure it compiles and run any tests that I may have for the package before creating a new package release. More on this below…

Project Layout

Unity has a suggested package layout convention documented and I’m going to take this format and embed it within a pretty standard Unity project layout.

<root>
  ├── Assets
  │   ├── Scenes
  │   ├── Scripts
  │   └── <package>
  │        ├── package.json
  │        ├── README.md
  │        ├── CHANGELOG.md
  │        ├── LICENSE.md
  │        ├── Editor
  │        │    ├── Unity.[YourPackageName].Editor.asmdef
  │        │    └── EditorExample.cs
  │        └── Runtime
  │             ├── Unity.[YourPackageName].asmdef
  │             └── RuntimeExample.cs
  ├── Packages
  └── ProjectSettings

You may find that you have other folders in the package for other assets, such as textures, shaders, sound files, or whatever. Modify as you see fit. The important part is that all files that should be part of your package should all live under the package directory.

I’m going to use a git trick to manage the package directory as a separate subtree branch from the main branch. I’m going to name this branch upm and will manage release tags off of this upm branch. git subtree is an alternative to submodules and in this case, allows me to break off of a chunk of the repo and manage it as a separate branch. This separate branch will then also be what Unity will end up pulling from, so when it loads a package from git, all it sees is the package subdirectory, not the entire project directory. Pretty cool, but takes some getting used to.

Once you get your project to match the layout above, proceed to the next step below.

Namespaced code

Perhaps this isn’t a mandatory step, but it’s usually a good idea to namespace your package code. The whole point of this demo is that you have a chunk of code you want to reuse, so to me it just makes sense to have all that code belong under a namespace as a way of organizing the classes. It’s real easy to do… In all of your <file>.cs files, wrap your classes with a namespace definition, like so:

namespace TyMesh {
    // Class definitions go here
}

All code that belongs to that namespace can reference any other public classes within that namespace directly. Any code outside of the namespace definition needs to reference using the full namespace.class path or by utilizing the using keyword. Basic C# stuff here.

Assembly Definitions

According to Unity: “You can use Assembly Definitions to organize the scripts in your Project into assemblies. When you create an Assembly Definition Asset in a folder, Unity compiles a separate managed assembly from all the scripts in that folder. Scripts in subfolders are included unless the subfolder has its own Assembly Definition. These managed assemblies act as a single library within your Unity Project.” You can read up on the properties and benefits of assembly definitions here.

You must create assembly definitions when creating packages, as referenced in the Unity docs. Note, that you should create separate assemblies for editor and normal code (see the assemblies referenced in the subfolders above).

Assembly definitions can be created within Unity. In your project panel, navigate to the Runtime folder as identified above. Right click in panel (or choose Assets in top menu bar), select Create, select Assembly Definition.

Give Unity a minute or so to bring up the inspector window for the newly created assembly definition. Under name, select the name of your project. Rename the asset file to also be your project name. If you have editor code, create a separate assembly for that, using a .Editor suffice to your package name.

package.json

Within the directory structure above, you’ll note that the top-level package directory has a package.json file. This serves as Unity’s Package Manifest and is a required file for Unity packages.

{
    "name": "com.ptjal.tymesh",
    "displayName": "TyMesh Dynamic Mesh Generation Package",
    "version": "0.2.0",
    "unity": "2019.2",
    "description": "tymesh - A Unity package providing methods for dynamic mesh generation"
}

Unity states that the name and version are the only required fields, but strongly suggest all of the above fields for better management and visibility of packaging. displayName gives user-friendly name to the package, as seen in the editor, description provides a brief package description that will display in the details view for the package, and unity identifies the lowest unity version the package is expected to be compatible with. See the manifest page referenced above for all the available fields.

Readme/License/ChangeLog

These are not mandatory files either, but provide some basic documentation and licensing for your package. Standard disclaimer, I’m not a lawyer, so I’m not going to tell you what you should or should not put for your license. Having a Readme is nice to give some context on what your package provides and/or how it should be used. A changelog is also nice to include, especially if you plan to make your package publicly available.

I’ll be showing how to use tags to reference package versions, so it is nice to have the change log, the package.json and the git tags in sync.

Packaging the Package

So, assuming you’re still following along, you’ve organized your project as described, created all of the required extra package files and you’re ready for the next steps. Here’s the basics of what we’re going to do next:

Commit all changes to main and push to master
Use git subtree to create a upm branch, pushing master content to upm and uploading to origin
Update the changelog and package.json with a new revision. Push those changes to master and the upm branch.
Create a tag on the upm branch for the new release.

Let’s start!

Commit

# commit your local changes and push to master
$ git add ...
$ git commit ...
$ git push

Git Subtree

# run from base directory of repo
# use gitsubtree to split your repo and push subtree to separate branch
# Assets/<package> should be the name of the folder containing your package files
$ git subtree push --prefix Assets/<package> origin upm

Create Revision

I’ve been using Semantic Versioning to label my releases. This uses a version string formatted as: major.minor.patch and gives guidance on when to use each. You are obviously welcome to use whatever versioning scheme works best for you. When creating a new revision, you’ll need to update the version in two spots: the CHANGELOG.md if you’re using it and the package.json.

# update package revision, e.g.: 0.1.0 might be my initial version for a package
$ vim CHANGELOG.md ...
$ vim package.json ...
# push revision changes to master and upm
$ git add ...
$ git commit ...
$ git push
$ git subtree push --prefix Assets/<package> origin upm

Tag the Release

# download and check out upm branch from origin
$ git checkout upm
# create tag for your release
$ git tag 0.1.0
# push tags to origin
$ git push origin --tags
# return to master branch, delete local upm branch
$ git checkout master
$ git branch -D upm

I remove the local upm branch after tagging to try to prevent any mistakes that could be made by commiting locally to the upm branch. The merging strategy for upm has all changes from master being directly pushed and merged to upm. No changes should be made directly to the upm branch.

Battle is half done and we should have a proper Unity package ready to be referenced.

Referencing a Unity Package

Luckily referencing a Unity package is much easier then creating them! I’ll show you two ways. For this part of the demo, I’m going to reference my modules from my old blog page, which I’ve updated now to be Unity packages:

tytest - A simple test framework
tymesh - A utility class for working with dynamic meshes
tysimpleshape - Another utility class that provide simple methods for drawing lines/dots in Unity

In this example tysimpleshape utilizes methods from both tytest and tymesh, so let’s take a look at how those dependencies can be met by using Unity packages.

Registry Hacking

Unity keeps track of all of your project’s package dependencies in the manifest.json located in your project’s Packages top-level folder. To reference a Unity package from a github repo, all you need to do is modify the manifest.json file, as outlined below.

{
    "dependencies": {
        "com.ptjal.tymesh": "https://bitbucket.org/ptjal/tymesh.git#0.1.0",
        "com.ptjal.tytest": "https://bitbucket.org/ptjal/tytest.git#0.1.1",
        ...
    }
}

You add a new line for each package dependency within the dependencies section of the file. Each line uses a key (e.g.:"com.ptjal.tymesh") and a value (e.g.: "https://bitbucket.org/ptjal/tymesh.git#0.1.0"). The key must match the name you assigned in the package.json file of the package. The value is URL for the git repository. Note that in this example, I’m referencing a specific version by appending the #0.1.0 syntax to the repo link.

Note: mind proper JSON formatting. I tend to make my additions to the top of the file, but if you add to the end, make sure don’t leave a dangling comma.

Unity’s Package Manager

I’m not 100% sure when this feature was added, but in Unity 2019.3, you can add references to git repos directly from Unity’s Package Manager interface. From the top menu bar, select Windows and Package Manager. This will bring up the Package Manager window.

In the upper left hand corner, click on the + button to add a new package. Select Add package from git URL ..., then enter the full URL and optional version info.

Both of these methods should cause Unity to download the package from the specified URL and integrate it into your project.

Private Repos

Well, the official word from Unity is that private repos that require authentication are not yet supported by Unity’s package manager. Reading on Unity’s forum threads it appears that this feature is high on their priority list and may come out in Unity 2020.1. I’ll keep my fingers crossed.

You may be able to work around this limitation by setting your local git client global config w/ credentials for you private repo. I was able to pull from a private repo doing this, but your mileage may vary.

Nested Dependencies

In general, it’s a good idea to have your packages all be nice, neat, self-contained packages without any dependencies on any other packages. And while this may be a goal to strive for, the reality is that you may end up with some dependencies that need to be accounted for in a package.

Fixing Assembly Definitions

If your package you’re building has code dependencies on other packages, as soon as you add an assembly definition for your new package, you will get compiler errors within Unity. This is because the assembly definition expects everything within the definition to be self-contained. However, you can add external dependencies to your newly created assembly definition.

Within Unity’s Project Window, find your assembly definition file and click on it to bring up the inspector. Find the Assembly Definition References panel:

Click the + at the bottom to add a new reference, then click the little bullseye to select your assembly definition from the available assemblies in your project.

Do this for all referenced packages.

Manually Managing Dependencies

Unity’s package.json definition file does have a dependency key that can be used for official unity packages. Unfortunately, it doesn’t seem to work for custom git references. So, this means that if your new custom package is dependent on other custom packages, you will need to manage these dependencies manually. All this really means is that when you go to pull the new package into another project, you will need to manually add any other dependent packages in as well. Not that big of a deal, but something to be aware of.

Maintaining Unity Packages

Updating a package follows the same procedure as setting up the initial upm branch and tagging.

Make your local changes to the project. Including changes to changelog and package.json Commit.
Use git subtree to push changes to your upm branch.
Create a tag on the upm branch for the new release.

# commit changes to master (including any changes to package.json)
$ git commit ...
# push changes to upm
$ git subtree push --prefix Assets/<package> origin upm
# checkout local upm
$ git checkout upm
# create tag for your release
$ git tag 0.1.1
# push tags to origin
$ git push origin --tags
# return to master branch, delete local upm branch
$ git checkout master
$ git branch -D upm

Try It Out

The referenced repositories are public. Feel free to try it out and/or poke around. Not much to look at, but here’s my little simple shape test:

tytest - A simple test framework
tymesh - A utility class for working with dynamic meshes
tysimpleshape - Another utility class that provide simple methods for drawing lines/dots in Unity

Credits

Credits go to Scott Doxey for documenting how to use subtrees and branches combined with Unity packages. You can reference his writeup here.

Hello World

2020-01-01T00:00:00+00:00

My Story

As with any good introduction into new territory, this story starts here at hello world. And I’ll build from there. Just want to provide a quick introduction for myself and to provide a little context to what I’m trying to do with this blog.

First, I am an aspiring game designer and developer. This has been a lifelong dream, but I have really only started working towards it in the past year or so. I am a software developer by trade and my real job is currently working in network and application security, focusing on secure software development and architecture along with cryptography and VPN technologies.

I am also a husband and father and part of a very active household. This put together with a real job means that I get limited time to work on gamedev. So my progress on projects and with this blog will not be at a rapid pace. But I continue to do what I can.

My Purpose

So, yes, this will be yet another game developer blog. There’s tons of them out there, so what am I planning on doing that will make this any different? Honestly, nothing. My intent isn’t to be flashy or new, but to simply document some of my experiences as a newcomer to game development. I plan to share some of the struggles I’ve had, including how I’ve overcome them. Tips, tricks, ideas and even failures are all fair game.

Throughout my learning experience, I’ve googled this and borrowed that. I’ve leaned heavily on those that have come before me and my sincere hope is that someone with similar interests and experience may stumble upon one of my articles and it may help them.

Some of the topics I plan on covering include:

Voxel engine and isometric surface extraction
Procedural generation
Constructed solid geometry
AI
Unity Tips and Tricks

Sneak Peek

The wonky little globe at the top of the article was generated from some procedural generation code I’ve been working on. Hopefully will have more details to come…

Delv

2019-04-28T00:00:00+00:00

The Game

An action adventure game.

My Contribution

Main menu (scroll art, opening animation, buttons, font selection, stone background, and related implementation), volume sliders, pause menu improvements, and particle options.

Play

This game was developed by members of the HomeTeam Gamedev club, myself included. Find out more about the club, or play this game: Play on itch.io

Media

Scrap Metal Elites

2018-05-28T00:00:00+00:00

The Game

A browser game made in HTML5. RC robot arena destruction!

Battle of the bots with physics-based destruction, breakable bots and lots of action. Become a contender in the challenging title matches to become the new Scrap Metal Elites champion or jump right into the action with the Death Match mode.

Game made in Unity.

My Contribution

Co-lead and project manager. Physics design/implementation for ram/spinner/hammer weapons, breakable parts, track and wheel steering, damage, and health. Blender modeling for modular bot cubes and bot panels. Arena camera controller and sound system/manager implementation.
Main UI design for main menu, bot selection, title round selection, in-game HUD including health-bars. Enemy AI implementation.

Play

This game was developed by members of the HomeTeam Gamedev club, myself included. Find out more about the club, or play this game: Play on itch.io

Find out more about the club here: Gamkedo Club.