Huy Minh Ha

Migrating Pelican to Hugo with an LLM

Mon, 08 Jun 2026 00:00:00 +0700

I’ve been running this blog on Pelican 3.4 since 2014. It worked, but the tooling was showing its age. I wanted to switch to Hugo — faster builds, simpler dependency story, and the Stack theme looked great out of the box.

Rather than doing the migration manually, I used an LLM (this very session) to walk through it step by step.

What the LLM handled

Conversion script: Wrote a Python script to convert 65 Pelican-format articles to Hugo frontmatter, handling field mapping, {filename} cleanup, and URL preservation.
Config scaffolding: Set up Hugo modules, the Stack theme, and all 6 config files (config.toml, params.toml, menu.toml, permalinks.toml, markup.toml, module.toml).
Deployment: Created a GitHub Actions workflow with hash-pinned actions for supply-chain security.
Asset migration: Moved avatar, favicon, and static images; verified all external image URLs.
Site verification: Ran through every page type, RSS, Disqus, syntax highlighting, dark mode, and search — all confirmed working.
Cleanup: Removed Pelican tooling (fabfile.py, develop_server.sh, pelicanconf.py, old themes, Pipfile), updated Makefile and README.

What I did

Made decisions on menu order, category merges (Web Development → Programming), and deployment strategy (GitHub Actions vs. manual).
Replaced the placeholder avatar with my actual photo.
Reviewed and approved each step.

Result

288 pages, 0 build errors, all old URLs preserved, and a much simpler publishing workflow:

1

git push origin source # that's it

The whole migration took one continuous session. The backup branch archive/pelican-source preserves the old setup.

Verdict

Using an LLM for this kind of structured migration was surprisingly effective. The heavy lifting — script generation, config wiring, verification — is exactly the kind of task LLMs handle well. The human stays in charge of decisions and quality control.

Setup Tmux with Vim for Mac

Fri, 03 Jul 2020 00:00:00 +0700

Why Tmux

When working on the Mac Terminal, I used to create multiple tabs. Then I can switch quickly between tabs using Ctrl + Shift + [ and Ctrl + Shift + ]. While this works smoothly, one annoying problem is all the tabs will lose their content after reboot. So I’ve been looking for a solution that supports:

Multiple tabs. Easily switch between tabs
Able to restore sessions

From my search, it’s quite obvious that tmux is the solution to my problem. Another candidate is screen, which I used for running some scripts on servers, but screen is pretty much a dead project now and its functions are far inferior to tmux.

My tmux settings

Tmux configuration is stored inside ~/.tmux.conf. On startup, tmux will pick up the content on this file and run it. We will put our customization code in this file.

First, we will remap reload key to r so that we can reload tmux.conf quickly.

1
2


# Set reload key to r
bind r source-file ~/.tmux.conf

Now, when we press <prefix> r, tmux.conf will be reloaded to reflect our new settings. The current <prefix> is still Ctrl B.

Remap prefix key

Prefix key is one of the most commonly used keys, so it’s super important to map it to a single key instead of Ctrl B or Ctrl A as some people might prefer.

On Mac, one popular solution is to change the prefix to Capslock key because it’s rarely used and very well positioned. We have 2 approaches to do this.

Approach 1: Remap Capslock to Esc and remap tmux <prefix> to Esc
- Go to System Preferences => Keyboard => Modifier keys to remap Capslock to Esc
- One annoying problem is now we have to press Esc or Capslock twice in Vim. This is quite unacceptable as I use Vim a lot
Approach 2: Remap Capslock to Home and remap tmux <prefix> to Home
- Normally you don’t have Home in Mac keyboard, but fortunately there is a software called Karabiner-Elements that allows you to completely customize your Mac keyboard.
- After that, remap tmux prefix key to Home:
```
 set -g prefix Home
 bind-key Home send-prefix
 unbind C-b
```
- I learnt this from https://blog.guilhermegarnier.com/2017/12/increasing-productivity-in-tmux-with-a-single-prefix-key/

Fast window switching

Windows in tmux are the same concept as tabs in Terminal. I want to be able to switch between windows quickly without having to lift up all fingers.

Fortunately, there’s an easy way to do this by mapping next-window and previous-window commands to Shift Right and Shift Left

1
2
3


# Shift arrow to switch windows
bind-key -r -T root S-Left previous-window
bind-key -r -T root S-Right next-window

You just have to hold Shift and press Left or Right arrows accordingly, which makes switching very fast.

Next, we also want to be able to move a window to the left and right. We’ll do this by mapping <prefix> n and <prefix> p to swapping a window with the one of the left or right

1
2
3


# Prefix n/p to move window to the left or right
bind-key -r -T prefix n { swap-window -t +1; next-window }
bind-key -r -T prefix p { swap-window -t -1; previous-window }

In effect, you will press Capslock n or Capslock p. However, unlike Shift Left key combination, you cannot hold Capslock. Instead, you will have to lift all your fingers and press 2 keys Capslock and n at the same time again. This is not a big problem since I’ll don’t usually move windows around a lot.

Restore Tmux and Vim sessions

When it comes to restoring tmux environment after system restart, the best solution is no other than tmux-resurrect. The installation instruction in their website is rather easy to follow.

After installing tmux-resurrect, we can use <prefix> Ctrl s to save, and <prefix> Ctrl r to restore tmux sessions.

Next and equally important, we also need a way to restore Vim session. I found vim-obsession works well with tmux-resurrect.

The part for tmux-resurrect in my .tmux.conf looks like this:

1
2
3
4


# tmux-resurrect
set -g @resurrect-processes '"~sudo pmset" "~Vim"'
set -g @resurrect-capture-pane-contents 'on'
set -g @resurrect-strategy-vim 'session'

Pay attention to the line set -g @resurrect-processes '"~sudo pmset" "~Vim"'. There are a number of default commands such as vi vim nvim emacs man less more tail top htop irssi weechat mutt that tmux-resurrect will automatically restore, but other commands outside of this list will not be restored automatically. So this line tells tmux-resurrect to restores extra commands if the command string match what is specified in the @resurrect-processes variable. In this case, since MacVim uses the command Vim and not vim, we have to specify "~Vim" so tmux-resurrect know that it should restore Vim window. Another command I use is sudo pmset, so I specify "~sudo pmset" here. For more details, read https://github.com/tmux-plugins/tmux-resurrect/blob/master/docs/restoring_programs.md

Finally, there are 2 problems when you restore tmux sessions. First, if you create temporary tmux session first, so that you can run the command <prefix> Ctrl r to restore previous sessions, you will have to kill the temporary session manually, which is annoying. Second, the restored windows will not have automatic-rename set to on, so their titles will not be updated automatically, which is equally annoying. To deal with these 2 problem, I use the following bash function:

1
2
3
4
5
6
7


mux() {
 tmux new -d -s delete-me && (tmux run-shell ~/.tmux/plugins/tmux-resurrect/scripts/restore.sh && tmux kill-session -t delete-me) &&\
 (for session_window in $(tmux list-windows -a -F '#{session_name}:#{window_index}'); do
 tmux set-window-option -t $session_window automatic-rename on
 done) &&\
 tmux attach || tmux attach
}

This function is modified from https://gist.github.com/rootulp/93f67511ae97c20c4d32b600a5ab6a8d. To use it, simply type mux in the terminal and it will restore previous session and reattach to it automatically. If there are multiple previous sessions, you can use tmux a -t <name> to attach to the session you want.

Vim binding in copy mode

Similar to screen, tmux has a copy mode to let you scroll through the content of your window, and copy/paste the parts you like.

Below is the setting to make this easier

1
2
3
4
5
6
7
8


# Use vim bindings in copy mode too
set -g status-keys vi # in the status/command prompt
setw -g mode-keys vi

# Setup 'v' to begin selection as in Vim
bind-key -T copy-mode-vi v send-keys -X begin-selection
bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "reattach-to-user-namespace pbcopy"
unbind -T copy-mode-vi Enter ; bind-key -T copy-mode-vi Enter send-keys -X copy-pipe-and-cancel "reattach-to-user-namespace pbcopy"

You can start the copy mode with <prefix> [. Then you navigate the window content with Vim-mode keys h j k l. v to start selecting. y or Enter to copy.

Customize Status bar

The default tmux status bar position is at the top, which is ideal for showing tab-like window titles. I want to maximize the space for showing window title, so I limit the left part and right part of the status bar to very basic information.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


# Set Colors
set -g default-terminal "screen-256color"
setw -g window-status-style fg=colour254,bg=colour102
setw -g window-status-format '#I:#W '
setw -g window-status-current-style fg=colour254,bg=colour30,bright
setw -g window-status-current-format '#I:#W '

# Set status bar
set -g status-bg colour252
set -g status-fg black
set -g status-left-length 90
set -g status-right-length 60
set -g status-left "#[fg=green]#S "
set -g status-justify left
set -g status-right ' #[fg=green]%a %d %b %R'

The left part of status bar, specified by status-left, only shows session title. The right part shows current date and time. Other colors and background colors are customized based on personal preferences.

Customize window title

For me, one important feature is a good window title, so that I can understand what’s in a window just by glancing at the title. One format that works quite well for me has these features:

Show full path of the current directory if possible. Replace home directory with ~ for brevity.
Limit the length of the path to 20 characters so that the title is not too long
But always try to show at least the full name of the current directory. This will deal with very long directory name that if truncated to 20 characters, will be hard to guess the full name.

The code to achieve these features is listed below. It uses awk because awk is best for one-liner kinds of programs.

1
2
3


# Set window title
set -g automatic-rename on
set -g automatic-rename-format "#(echo '#{pane_current_path}' | awk '{split($0, a, \"/\");basename=a[length(a)];cmd=\"pwd\"; cmd | getline homepath; close(cmd);baselength=length(basename);i=index($0,homepath);path=$0;if (i==1) { path=\"~\"substr(path,length(homepath)+1,length(path)); };maxlength=15; if (length(basename) > maxlength-3) { print \"../\"basename; } else if (length(path) > maxlength) {print \"..\"substr(path, length(path)-maxlength+3, length(path)) } else print path }') - #{pane_current_command}"

If you want to customize this code, you can change maxlength=15 to whatever you like. If you want to customize further, then you need to get a bit more involved with awk

The result is pretty good as far as I’m concerned. Here are some examples:

~/work: Shorter than 15 characters, so it shows full path
..rk/webarchive: full path is ~/work/webarchive, so it truncates to 13 characters and replaces the rest with ..
../a-very-long-folder-name: The folder name itself is longer than 15 characters, so it’s kept in tact and then prefixed with ../

Conclusion

Those are my main points of customization of tmux. Granted there are other functions that can be customized such as pane splitting, pane switching, mouse mode, etc, but I don’t use those functions much if at all in my every day activities.

My tmux settings can be found at https://github.com/minhhh/dotfiles/blob/master/tmux/.tmux.conf

Setup nodejs development environment with conda and nodeenv

Fri, 09 Aug 2019 00:00:00 +0700

When you want to develop your nodejs project on different node versions, you have some tools to help you install multiple node versions such as nave, nvm, n. However, this is still not as nice as virtualenv in Python, where you have completely isolated environments so one project does not affect the others.

Fortunately, there is a tool called nodeenv that can help you create isolated node.js environment the same way as virtualenv. Using nodeenv is already good enough, but if you don’t want to store the virtualenv folder in the same project folder, then you would need some other tool to manage virtualenv folders globally. There are 2 options: conda and pipenv. pipenv does not integrate very well with shell scripts because you have to start a separate pipenv shell. conda is perfect because it can manage all kinds of packages, not just Python or nodejs and it’s very compatible with shell scripts.

In conclusion, using conda and nodeenv is a much better choice than just nave or nvm.

Webview with schema

Mon, 08 Jan 2018 00:00:00 +0700

The unity-webview plugin is nice, but one thing is you have to call Unity.call from Javascript. This is not very convenient for those who design the HTML to quickly assign action related to Unity in hyperlinks.

So I added support for calling Unity function using normal links in HTML using the schema unity://. For example, we can put the link: unity://scene?param1=value1&param2=value2. When clicking this link, the string scene?param1=value1&param2=value2 will be passed to Unity, then we can use WebViewHelper to parse it furthur into scene, param, value1, param2, value2 and so on.

Colored Project Folder

Mon, 27 Nov 2017 00:00:00 +0700

ColoredProjectFolders is a simple plugin that color some special folders in the Project View so that you can find them more easily. It is inspired by Rainbow Folders.

There’s only 1 script Assets/ColoredProjectFolder/Editor/ColoredProjectFolder.cs. You can modify it to add more hard-coded folder names. You can add or modify folder icons in the same folders. This could be made into a customizable setting, but I feel the usage is the same as just modifying the script directly.

Test AssetBundle in Unity 2017

Tue, 14 Nov 2017 00:00:00 +0700

With Unity 2017, we can use 2 tools to build Asset Bundle: AssetBundles-Browser and AssetGraph. I’ve created a test project here

General flow

Setup Asset Bundle Graph to build AssetBundles
Check AssetBundles with AssetBundleBrowser

Setup Asset Bundle Graph

The most basic setup consists of 4 nodes:

Load From Directory
Group By File Path
Configure Bundle From Group
Build Asset Bundles

In step 1, we create a folder that represents all resources related to an entity in our system, this could be a character or an enemy NPC. In step 2 we want to create one AssetBundle for each of the sub-folders in the parent folder. Each AssetBundle represents an aspect of the entity, such as by resource types: textures, materials, animations, or by enemy types: fast, slow. Step 3 applies naming convention to the AssetBundle’s name. Step 4 is obvious, building the final asset bundles.

There are 2 examples of Asset Bundle Graph (ABG) in Assets/Tests: ABG_with_regex and ABG_with_wildcard.

In the ABG_with_regex example, we used the pattern /Missile\/(.*)/. There are several issues with this approach:

It’s not real regex since we cannot use (.+) and we are forced to use (.*).
It creates group for sub-sub-folder. For example, it creates a group named Object/Materials instead of just putting it inside group Object
The main blocker issue is the error Moving file failed when building AssetBundles

In the ABG_with_wildcard example, the group is created correctly for each of the sub-folders. There is still some issues:

We cannot have . in the group name because if we do then the part after . will be considered variant.
We cannot have variants of sub-folder, we have to use the folder name itself as variant

This is just a rough test and obviously we require much more for an usable workflow.

Unity plugin USplitAlpha

Thu, 26 Oct 2017 00:00:00 +0700

Last time I discussed about Unity texture compression I’ve mentioned that using ETC1 + Alpha channel is the best format because it provides the best build size and memory footprint in most cases. However, Unity does not support split alpha channel for iOS. Recently I had sometime to revisit this and wrote a simple plugin to support split alpha channel on both Android and iOS devices. The plugin is called USplitAlpha.

Apparently, the split alpha mechanism is very straightforward so different team will have different workflows that suit them best. For reference, there are some other solutions on github:

Loading Sprites dynamically in Unity

Sun, 06 Aug 2017 00:00:00 +0700

Loading sprites dynamically from code is one of the most basic tasks that we have to do. However, it seems that there’s not a standard way to to this in Unity. This guide will look at several cases of loading sprites dynamically and their solutions

1. Loading a separate sprite

Imagine you have 4 attribute icons: fire, water, earth and wind. You will have to load the correct icon for the correct character. The easiest way to do this is to put 4 icon images: fire.png, water.png, earth.png and wind.png inside a folder in Resources, such as Resources/attribute_icons/. Then loading a sprite is as simple as this:

1

Sprite sprite = Resources.Load ("attribute_icons/fire", typeof(Sprite)) as Sprite;

In reality, we almost never do this. The reason is we need to batch drawcall, so we cannot afford to have separate drawcall for each of these small icon images. But if you put the sprites inside the Resources folder, you cannot pack them with Unity’s Sprite Packer. If you put them outside of the Resources folder, you cannot load them dynamically with Resources.Load. This leads to the next solutions.

2. Packing spritesheet with external tools

Unity has a Sprite import mode called Multiple, where you can slice a Sprite atlas or Spritesheet into multiple sprites. The sprites can then be load dynamically like this:

1
2
3


// suppose the texturesheet is in Resources/attributeicons.png
Sprite[] sprites = Resources.LoadAll <Sprite> ("attributeicons");
// Find the correct sprite to use by Sprite.name

Obviously, you would not want to create the Sprite atlas and slice sprites by hand in a real game (not a tutorial). Therefore, you will use an external tools to create the Sprite atlas. There are several solutions:

Write your own texture packer (or use an existing one you can easily find in github). Remember to export the UVs information to text, or json and copy it to Unity. In Unity, you have to write an Editor extension to slice the Sprite atlas using the Uvs information in the text/json file. I have a tool and Unity code for this but I cannot publish them due to copyright. They’re super easy to create though.
Use a full solution inside Unity. You will have the original textures in Unity, then the Sprite atlas will be created inside Unity easily by dragging, dropping sprites to the tools, or some other similar method. You can try the asset SimpleSpritePacker.
Use TexturePacker. This is the best solution since it creates much more optimized sprites. But it costs 40 dollars.

3. Packing sprites using Unity Sprite Packer

One big disadvantage with using external tools is that you cannot move sprites easily. If you move a sprite from one path to another, you will have to update the path in all objects that use that sprite. Using Unity sprite packer, you can do it like so:

Mark a Sprite with a packing tag
Use the sprite in a GameObject or Prefab freely
A spritesheet will be created by Unity automatically. The sprite will be loaded automatically from that sprite sheet.

So this is perfect, but you cannot load sprite dynamically anymore? There’re 2 solution for this problem.

First, you can add all the needed sprites to whatever objects using them, then enable/disable the correct ones by code. This solution works for small projects but it does not scale.

The second solution is to use a tool that automatically load all the sprites into a prefab that can be loaded dynamically in runtime. A sample of this solution is https://github.com/minhhh/UBootstrap.SpriteCollection

Note that sometimes this option is not possible. For instance, you have to use a special material and shader, then the material might not work with Unity Sprite Packer. In one project that I worked on, we have custom SplitAlpha shaders that do not work with Unity Sprite Packer and SpriteRenderer. In those cases, you have to use solution 2.

Unity Asset Reference Finder and Missing Script Finder

Mon, 10 Jul 2017 00:00:00 +0700

When using Unity, you often have to check which GameObject or Prefabs are using a certain image or other types of assets. There’s a convenient tool for you to check which objects are using a certain asset: AssetReferenceFinder

Another tool called MissingScriptFinder helps you find missing scripts in scene due to refactoring

Unity Prefab Best Practices

Thu, 06 Jul 2017 00:00:00 +0700

Link prefabs to prefabs; do not link instances to instances This is from 50 Tips for Working with Unity

Use GameObject.Find to establish links between instances if you have to. It’s best to not having to establish links between instances and use prebabs instead. Don’t link instance to instance like this article suggests (https://akbiggs.silvrback.com/please-stop-using-gameobject-find)

Apart from UI component, refrain from using GameObject.Find because there are many better alternatives such as using interfaces, dependency injection, design patterns and so on.

Use Editor script to warn you of missing links in the Editor like this one: https://github.com/redbluegames/unity-notnullattribute. However, it will not work when you use the same prefab for multiple gameplay modes, each with its own set of required component. In that case, you will have to use inheritance or duplicate code in a new component.

Remove prefab links from scene object (https://github.com/minhhh/unity-tips/blob/master/README.md#tips-using-editors)

References

How to backup your gmail account

Fri, 26 May 2017 00:00:00 +0700

The 2017 ultimate guide to Gmail backup

If you want to backup mail from one gmail to another gmail you can use the following software:

Introducing UAsync

Mon, 08 May 2017 00:00:00 +0700

Nowadays, if you want to use a structured way for your flow control in Unity, you basically have 4 options:

Write your own Task library (which might use coroutines)
Use coroutines. This means that you StartCoroutine in a lot of places and insert try catch code when errors occur. This works for small games. For larger games, not being able to catch nested exception is a big NO NO.
Use C-Sharp-Promise. If you’re familiar with JS promises, this comes natural to you. It handles exceptions pretty well. You can try combining this with coroutine, but the API is probably verbose.
Use UniRx. This is simply the best choice because it supports control flow, exception handling, progress report and coroutine.

So we should always use UniRx, right? Unfortunately, sometimes the efforts to use UniRx is just too much that we can’t afford. In that case, it’s better to use existing solution, but with more robust code. (C-Sharp-Promise is ofcourse another option, but it is not compatible with coroutine and existing coroutine code without some custom modifications).

UAsync Unity Async is a library that helps you write Unity code using callback style of Node.js and async library. The TaskRunner part is taken from Svelto.Tasks with some modifications to make it support catching exceptions and returning errors. The UAsync class adds several functions on top of TaskRunner to support execution of tasks in parallel or serial with returned results at the end of the execution. For the moment, it does not support Thread because it focuses on control flow, not enhancing performance by distributing work to multiple cores.

To include UAsync into your project, you can use npm method of unity package management described here.

Usage

TaskRunner

First of all, it’s quite well-known that 2 main disadvantages of coroutine are: 1) it cannot return value and 2) it cannot handle nested exception. There’s a simple way to wrap coroutine so we can support those 2 features, as detailed in this article. TaskRunner also supports returning value and catching exceptions using callback style. You use it like so:

1
2
3
4


using UAsync;
...
TaskRunner.Instance.Run (task, onComplete);
// public TaskRoutine Run (IEnumerator task, CallbackDelegate onComplete = null)

In the code above, task is a IEnumerator and onComplete is a delegate of type CallbackDelegate (object err = null, object res = null). Any exceptions occur will be passed via err. The last yield in task will be passed to res. You might want to use TaskRunner.Instance.Run when you have a sequence of actions to be performed in a fixed order.

UAsync

UAsync is a port of Node’s async module to Unity environment. It can be used to turn a set of synchronous functions or coroutine to run sequentially or concurrently. Even though you can already run a set of tasks sequentially using coroutine, passing values between these tasks are proven to be difficult. You have to use external variables to hold the return values which creates coupling between functions, and it’s not convenient. UAsync can solve this problem by allowing coroutine to return value, as well as catching exceptions if any.

Let’s look at an example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


var series =
 UAsync.Async.Series (
 SeriesFunc.FromAction ("one", SeriesFunc1),
 SeriesFunc.FromEnumerator ("two", SeriesFunc2),
 SeriesFunc.FromAction ("three", SeriesFunc3),
 UAsyncFinalFunc.From ((object err, Dictionary<string, object> res) => {
 Debug.Log ("Finish " + err);
 if (err == null) {
 Debug.Log ("res " + res ["one"] + " " + res ["two"] + " " + res ["three"]);
 }
 })
 );

void SeriesFunc1 (CallbackDelegate cb, Dictionary<string, object> res)
{
 cb (null, 100);
}

IEnumerator SeriesFunc2 (CallbackDelegate cb, Dictionary<string, object> res)
{
 yield return new WaitForSeconds (1);
 cb (null, 200);
}

void SeriesFunc3 (CallbackDelegate cb, Dictionary<string, object> res)
{
 cb (null, 300);
}

Here, SeriesFunc.FromAction and SeriesFunc.FromEnumerator are just convenient functions to wrap synchronous functions and coroutines. Each of the functions SeriesFunc1, SeriesFunc2 and SeriesFunc3 will receive a callback parameter and a res parameter. To complete the execution of each function, you must call cb with 2 parameters: err representing the error, and result representing the returned value. In the code above, there is no error. If any of the code in those function throws exception, cb will also be called automatically with the exception as the first parameter.

The second parameter passed to each of the functions SeriesFunc1, SeriesFunc2 and SeriesFunc3 is quite important. It is a dicionary which contains all the results from previous functions, so SeriesFunc2 will receive result from SeriesFunc1, SeriesFunc3 will receive results from SeriesFunc1 and SeriesFunc2. The key of the dictionary are declared when creating the series, e.g. SeriesFunc.FromAction (“one”, SeriesFunc1) means the result of SeriesFunc1 will have key “one”. This is a powerful way to pass results between functions without creating high coupling between them.

After all the functions have been executed, there is a final function UAsyncFinalFunc which will receive all the results and execute some logic accordingly. If any of the functions above throws exceptions or calls callback with a err parameter, the error will be passed to the final function to deal with.

The UAsync.Async.Parallel function is similar to the Series function, except that there will be no results from previous functions since they’re executed concurrently.

Finally, you can cancel a running sequence once it’s started. This is not obvious with coroutine because even though you can call MonoBehaviour.StopCoroutine

Using Unity Assert

Tue, 25 Apr 2017 00:00:00 +0700

Even though Unity’s UnityEngine.Assertions is great, it has two major disadvantages

We cannot extend it
It does not have the concept of error code. Using error code, we can force developers to explicitly think about how they will categorize the error so it’s easier to analyze the error when the game crashes

Therefore I put together a simple script to do assertion here: https://github.com/minhhh/UBootstrap.Assert

Our CUSTOM_ASSERT class provides the almost the same interface as UnityEngine.Assertions.Assert:

IsTrue (bool condition, int errorCode, string message = "", params object[] args) - Asserts that the condition is true.
IsFalse (bool condition, int errorCode, string message = "", params object[] args) - Assert that condition is false
IsNull (object value, int errorCode, string message = "", params object[] args) - Assert that value is null.
IsNotNull (object value, int errorCode, string message = "", params object[] args) - Assert that value is not null.
AreEqual<T> (T expected, T actual, int errorCode, string message = "", params object[] args) - Assert that the values are equal.
AreNotEqual<T> (T expected, T actual, int errorCode, string message = "", params object[] args) - Assert that the values are not equal.
AreApproximatelyEqual (float expected, float actual, int errorCode, float tolerance, string message = "", params object[] args) - Asserts that the values are approximately equal. An absolute error check is used for approximate equality check (|a-b| < tolerance). Default tolerance is 0.00001f.
AreNotApproximatelyEqual (float expected, float actual, int errorCode, float tolerance, string message = "", params object[] args) - Asserts that the values are approximately not equal. An absolute error check is used for approximate equality check (|a-b| < tolerance). Default tolerance is 0.00001f.
Fail (int errorCode, string message = "", params object[] args) - Just fail the assertion.

The reason it’s named CUSTOM_ASSERT is to make it look like a macro definition. In fact, you have to define a macro named CUSTOM_ASSERT to include it in your build, similarly to the macro UNITY_ASSERTIONS from Unity.

CUSTOM_ASSERT class is defined as a partial class. It is expected that you define your part of the partial class, so that you can provide some default error code for common functions. You can find an example in Assets/MY_ASSERT.cs. It is also recommended that you define your own sets of error codes.

There is no way to include the assertion without throwing exception, because it does not make sense to assert something that does not crash the build if its not true. Those set of errors belong to a logger, not an assert utility.

Resources for learning Blender

Tue, 21 Mar 2017 00:00:00 +0700

This is collection of resources for learning Blender from the beginning

Blender 3D Design Course
Unity Mega-Tutorial: Blender 3D Modelling Tricks, High-Speed Physics, and Real-Time Reflections!
Blender 2.7 Tutorial
Learning 3D modelling as a single indie developer
12 (More) Blender Addons Everyone Should Use
Low poly
- Low Poly Planet
- Learn to Create Geometric Assets in Blender
- GAME ASSET TUTORIAL In this Video Tutorial series for Beginners, we will create Low Poly Barrel Game Asset using Blender, Photoshop, and Unity.
- Create any low poly animal | Blender | 10 mins

Unity Jelly Physics

Tue, 14 Mar 2017 00:00:00 +0700

There are several plugins to help creating a jelly like physics in Unity:

Unity Mesh Morphing

Thu, 09 Mar 2017 00:00:00 +0700

There are several ways to do mesh morphing in Unity.

One way is to use a commercial plugins like Megafier

You can use a simple script to do mesh morphing as well: https://github.com/minhhh/unity-meshmorphing. Remember to make all your mesh have the same number of vertices.

How to force Gmail to check your POP3 account as often as possible

Mon, 27 Feb 2017 00:00:00 +0700

How to force Gmail to check your POP3 account as often as possible

Unity Object Pooling

Fri, 24 Feb 2017 00:00:00 +0700

An object pool provides an efficient way to reuse objects, and thus keep the memory foot print of all dynamically created objects within fixed bounds. This is crucial for maintianing consistent framerates in realtime games (especially on mobile), as frequent garbage collection spikes would likley lead to inconsistent performance.

Implementing object pool is quite straight forward. There are several open-source solutions already so don’t bother looking into AssetStore.

Unity Unit testing

Tue, 21 Feb 2017 00:00:00 +0700

How to use the Integration Test Framework is the guide from offical repo

Writing Integration Tests For Unity3D Projects

Suggests writing dynamic integration test on real game scene. This might be hard to maintain if you don’t have discipline.

Property Backing Field Drawer

Tue, 14 Feb 2017 00:00:00 +0700

Property is not supported by Unity Editor by default, fortunately, there is a free plugin called Property Backing Field Drawer that supports drawing custom editor for properties. The plugin’s code is extracted here for easy inclusion in your project.

Better Unity workflow with command line

Thu, 02 Feb 2017 00:00:00 +0700

To do certain tasks for our game workflow, we will need to use other external tools that can only called from the command line. One way to do this is to switch back and forth between Unity and the command line, obviously this is not the best way. Our goal is to use only 1 click, or one action to execute a series of tasks in Unity and in the command line.

There are 2 ways to achieve this:

Create an editor script and call the command line, along with other Editor scripts. This is good if you want to stay in Unity all the time.
Create a command line script that call other command line scripts and some Unity scripts. This is good for continuous integration.

To launch Unity from the command line, look at these references:

To run command line scripts from Unity, look at these references:

Running command line action through C# script

Best Practices in Persisting Player Data on Mobile

Wed, 01 Feb 2017 00:00:00 +0700

Original talk: Unite 2016 - Best Practices in Persisting Player Data on Mobile

Using Webp texture format in Unity

Wed, 18 Jan 2017 00:00:00 +0700

Webp is a very optimized image format. It will produce smaller image size with almost the same quality as other compression format such as: ETC2, DXT5, ETC1, PVRTC. Below is some comparison between Webp and popular compression format in Unity

512x512 Image	Size in KB
Original	480
ETC1 4bits	128
ETC2 8bits	256
Dxt5 Crunched	64
PVRTC 2 bit	64
PVRTC 4 bit	128
Webp Lossless	287
Webp Lossy 80	23

1024x1024 Image	Size in KB
Original	1800
ETC1 4bits	512
ETC2 8bits	1000
Dxt5 Crunched	183
PVRTC 2 bit	256
PVRTC 4 bit	512
Webp Lossless	1200
Webp Lossy 80	113

I’ve written a simple plugin to include Webp textures into your Unity game here: https://github.com/minhhh/UBootstrap.Webp

Ref: png vs webp

Git branching strategy

Mon, 09 Jan 2017 00:00:00 +0700

Branching strategy is an important part of using git correctly. Without a proper branching strategy, even with a few people in the project, you will create a mess in no time. Below is a simple branching strategy that can be applied to various situation. It is also available on github here

Branch Description

master

Master branch represents what’s in live. It should not be modified directly.

When it is deployed, it will be tagged so that we can revert to a certain deployment later.

Lifetime: forever

release/xxx

After finishing a feature, make a release branch off the develop branch, merge all the necessary feature branches and do final test. Bugs found in this final QA phases can also be hotfixed in the same branch. After everything is complete, we will rebase this branch over develop branch, then the rebase branch will be merged into the master branch for release in Live environment.

Lifetime: Feature Finish ~ Release in Live

hotfix/xxx

If a bug is found in production, we wil branch hotfix branch off master.

Lifetime: Bugfix ~ Release in Live

develop

This is the main branch where feature branches should be branched off. Trivial changes can be directly applied to develop if you are sure it should go into the next version. Major feature/bugfix branches have to go through PR process to be merged into develop.

Lifetime: forever

feature/xxx

Feature branch should be branched off develop. While working on feature branches, developers can choose to merge develop into it. Once QA is completed on the feature branch, developers can send PR.

Lifetime: Feature development ~ PR merge

art

Art branch lives forever. Artists only need to deal with this branch.

Lifetime: forever

Role Descriptions

Engineer / UIDesigner

develop -> feature
feature -> develop (PR)

Artist

art -> art

Lead Engineer

develop -> release
release -> develop
master -> hotfix
hotfix -> master
hotfix -> develop

Unity package management

Mon, 09 Jan 2017 00:00:00 +0700

A robust package management system is quite important when developing in Unity. People have been asking for one in the Unity forum. The following survey will list some popular options.

Projeny The purpose of Projeny is to allow your Unity3D project to easily scale in size without heavily impacting development time. Only available in Windows

Share any Unity assets (code, scenes, prefabs, etc.) across multiple different Unity projects without copy and pasting
Instantly switch between platforms
Easily upgrade or downgrade installed asset store packages
Optimize compile time of your project by getting Unity to only recompile the code that changes most often
Split up your project into discrete packages, so that you can manage the dependencies between each, instead of having one giant Unity project of inter-related files
Declare dependencies between packages, so that you always get the packages that you need without needing to hunt down missing libraries or broken links
Generate a more intelligent Visual Studio solution than the Unity default, using package dependencies to create csproj dependencies

NPM can be used to manage packages and their dependencies

It’s very easy to use and install.
Can be used with private repo
Cannot distribute .unitypackage file
However, without using private registry, it cannot force resolve to the latest versions of all dependencies. This issue can be resolved using yarn install --flat

Some people suggests using NuGet

Seems can download packages correctly
Have to install a central server to make it work

Paket.Unity3D

Same problem as nuget
Seems to work better in Windows

Unity Kaizen

Deliver packages via a central repository and zip
Require more work from package maintainer

UPM

UPM is a package manager designed to work with the Unity game engine. It allows rapid install of unity extension and assets using a command line interface. Packages support dependencies, which will be auto-downloaded when installing a package.
Seems to be unmaintained
No MacOS binary

unity-packman

A command-line client to manage Unity package
Does not support version and nested versions
Can only export 1 directory, which is really limited

Dither Unity textures to save memory

Thu, 05 Jan 2017 00:00:00 +0700

The project code is here: https://github.com/minhhh/unity-texture-dither

In many cases, we want to dither textures so that we can use more compact texture import format to save memory. This project aims to provide a workflow for dithering imported texture automatically, based on settings that can be swapped easily. Note that this has nothing to do with using dithering to achieve some artistic goal or the real time dithering effect to solve color banding problem.

The algorithms are explained in a blog post by Tanner Helland and the reference implementations are taken from https://github.com/mcraiha/Dithering-Unity3d with some slight modification.

Usage

To dither images, put them in a folder whose name ended with Dither. Then click on the folder and Reimport.

The dither setting, i.e. algorithm and output color space is defined in ScriptableObjects DitheringAlgorithmSetting. You can find them in the Assets folder. To change dither setting, select Settings > TextureDitherSetting and change the field Dither Algorithm Setting accordingly.

Supported algorithms are:

Atkinson
Burkes
FloydSteinberg
JarvisJudiceNinke
Sierra
SierraLite
SierraTwoRow
Stucki
No Dithering (for testing purpose)

Supported color spaces are:

RGBA4444
Websafe
TrueColor (for testing purpose)

Using Unity Mecanim animation system

Mon, 02 Jan 2017 00:00:00 +0700

See unity-mecanim for sample code of this article

Mechanim basics

animation parameters

Animation Parameters are variables that are defined within an Animator Controller that can be accessed and assigned values from scripts. This is how a script can control or affect the flow of the state machine.
Parameters can be assigned values from a script using functions in the Animator class: SetFloat, SetInt, SetBool, SetTrigger and ResetTrigger
Mecanim Animation Parameter Types: Boolean vs. Trigger
Parameters can also be controlled in animation using Curve and read in script
- You cannot control an Animation parameter from both Curve and Script, so you have to structure your code correspondingly.

Root motion, Blend Tree

RPG Character Controller 001 - Unity 5 Root Motion

Layer, Layer Mask

Layer Usages (Animator Controller Layers)
- Additional layer for handling different body parts while the base layer handles the base movement, such as: wave hand while moving
- Blending mode can be: Override or Additive. Normally Override will be used because using Additive can be highly unpredictable unless you’re an advanced animator. (advanced animation)
- Blend additional movement based on character state such as: heavy breathing when tired
- Sync layer when you have a set of animation for when the character state changes such as: wounded animations
Avatar Mask(Avatar Masks)
- Could be set in animation to see the effect of Masking only part of the body
- Normally apply to layer which controls part of the body (advanced animation)

Equip weapon

Equip immediately without animation
- For models created in Unity
  - Create weapon holder node
  - Attach the weapons to it
  - Hide/Unhide the correct weapon when switching weapon
- For models created outside Unity
  - Find the correct node in the model OR create a weapon holder node like before
  - Attach the weapons to it
  - Hide/Unhide the correct weapon when switching weapon
Equip with equip/unequip animations. All weapons are treated the same when equipped (Sword equipping)
- Create equip/unequip animation for each weapons
- Using layer/layer mask to blend the equip/unequip animations, masking only the necessary parts of the body, such as the arm movement
- Using Animation Event to set value to flags such as: sword_equipped, sword_unequipped
- Attach the corresponding weapon using Animation Event calling functions and/or flags
Weapons affect whole animation when equiped (Applied Mecanim : Character Animation and Combat State Machines)

Using mechanim as state machine

Mecanim as generic state machine
Reusing animator controllers with AnimatorOverrideController
Applied Mecanim : Character Animation and Combat State Machines
- A character with
  - 8 weapon types
    - 9-12 ground attacks
    - 5 aerial attacks
    - 3 defensive maneuvers
  - 4 throwable items
  - 6 classes of magic each with 3-6 abilities
  - Basic locomotion, jump, hit react, death
- One way is to use SubStateMachine, with several depth layers
- An alternative organization is to use BaseLayer with Overrides Layer and Additive Layer
Leveraging Unity 5.2’s Advanced Animation Features
- You can manage all transitions between attacks manually
- Or you can use a blend tree. This is slightly better. One problem is if you change the Blend parameter while playing animation, it will change the animation immediately.
- Solution in Unity 5: StateMachineBehaviour on a State. This way you can have code that run at the Start or End of your blendtree.
- You could also have StateMachineBehaviour on a StateMachine. Then you can override OnStateMachineEnter and OnStateMachineExit functions
- When the SubStateMachine is a sequence of animations, you can have code on OnStateMachineEnter to equip weapon
- Can also check for Input in StateMachineBehaviour

Best Practices

Animation events not firing when the event is near the endframe, so either use a third party event dispatcher, or use StateMachineBehaviour.
Use custom class to cache animation event
- You might catch animation events using a general event handler function such as OnAnimationEvent (AnimationEvent), however this might not be the best solution since you will have to do a switch case in your main logic class. This will make the main logic class (e.g. Enemy, Player) knows too much about the flow to handle animation event. Also you might not be able to reuse common code.
- A better way is to have a generic custom class to handle animation event, e.g. AnimatorHandler. This class will have most common function such as OnAnimationStart, OnAnimationEnd, OnAnimationUpdate. You can pass custom handle functions in as callback if you need to. This class also has common utility function such as getting current state name, check if any animation is playing etc.
When importing animations, make sure to Bake into pose the part where you don’t want to move by Root motion. Also use Offset to fix Average velocity not zero problems, e.g. walking animation that has a X speed
Change the animation speed of specific layer
- There’s no way to change the animation speed of specific layer. The current best way is to Use blend tree to control the speed of a particular layer based on parameter. See Mecanim - Change animation speed of specific animation or layers
- You can also change the speed of particular state in Editor and via script
Use int parameter instead of boolean or trigger. This way you can use AnyState to transition using condition such as skill=1, then when entering the mecanim state we set it to another number immediately Applied Mecanim : Character Animation and Combat State Machines
Use substate to simplify your state machine. However, becareful when constructing AnyState transition to deeper substate, since AnyState is global. In this way, we can ignore the immediate substate and only care about the final subtate. We use the most specific condition, such as skill=1 and subskill=2 to trigger the final substate from AnyState. This way we don’t have to configure transition to immediate substate and only care about the final state
Use SMB: Applied Mecanim : Character Animation and Combat State Machines
- SMB makes sure that OnStateMachineExit is called when exiting a state. Putting a animation event at the end of an animation cannot ensure that for 2 reasons: The animation might be forced to switch in the middle or the animation event might not fire because the animation is played too quickly
Running an animation completely before transitioning back
- Make sure Exit time is 1.00, with FixedDuration unchecked.
How to Run the death animation then destroy GameObject
- Use a timer. This is quite a robust solution but maybe not visually correct in some cases, i.e. the animation might be stopped too soon.
- Use animation event. Add an Exit event to the animation at the last frame. This is not very robust, since Unity might skip Animation event
- Use auto transition to a fake after death state. Then use StateMachineBehaviour to detect when we exit the Death state. This is also a robust solution, but requires you to modify the structure of the Animator.
How to transition out of a substate machine (Using substate machine)
- Using Up node: Transition to state or StateMachine
- Using Entry/Exit nodes: Transition to/from StateMachine. This facilitates better reusability
- Try to only use one way

Finite state machine for Unity

Wed, 28 Dec 2016 00:00:00 +0700

Finite State Machine (FSM) is an important technique in game programming. Most games that have some sort of battle will have to design an FSM for its entities. FSM can be applied in UI as well. For example, instead of using flags to enable/disable certain UI elements, we can use a full FSM for all possible states of the targetted UI and its interactions with user inputs.

The main elements of a FSM include:

A representation of a state
A representation of a transition between 2 state
A central system that hosts the states and facilitates their transitions

Using Interfaces to Make a State Machine for AI has a simplest implementation of FSM. A state is represented like this:

1
2
3
4
5
6
7
8


public interface IEnemyState
{
 void UpdateState();
 void OnTriggerEnter (Collider other);
 void ToPatrolState();
 void ToAlertState();
 void ToChaseState();
}

This implementation hardcodes all state transitions in the interface, thus it’s a bad example and should not be used in a serious game.

A simple finite state machine with C# delegates in Unity provides a slightly better implementation. Instead of hardcoding, it calls a single delegate function when making a transition. Still, it does not separate actions to be executed upon entering and exiting states, so it’s not very useful for serious purpose.

Finite State Machine by Unity Wiki does provide overridable functions to be executed when entering and exiting states. However, we also need to perform actions in Update, FixedUpdate and similar functions for entities that have time-based changes such as a player, enemies, NPC and so on. So this implementation is not sufficient.

Unity3D Finite State Machine satisfies functionality requirements. It provides on enter/exit functions as well as Update, FixedUpdate, LateUpdate. It does not use separate State class, instead, it uses reflection to call the correct function in the main Component for each state. Therefore, all functions of all states must be defined in the main Component, for instance, Play_Enter, Play_Exit, Init_Enter, Init_Exit, Move_Enter, Move_Exit.

My own implementation of Finite State Machine is similar to the above method, except that I don’t want to use generics, since it will make it harder to refer to the FSM using code.

Another way to implement FSM is to make each state a separate MonoBehaviour. In this way, you can separate the functions for each state in its own file. In addition, you can examine the states in the Editor easily, like other MonoBehaviour. One issue which needs to be solved is how to access the members of the main Component. So you have to pass in the main Component to the state via constructor and make the members public. An alternative way is to write generic singletons which can be accessed from anywhere.

References

Understanding Unity Editor Extensions

Thu, 22 Dec 2016 00:00:00 +0700

Unity Editor offers many ways for extending its functionality to suit your project’s specific needs and workflow. Have a look at unity-editorextension-manual for a complete list of ways you can extend the Unity Editor.

Understanding Unity ScriptableObject

Thu, 15 Dec 2016 00:00:00 +0700

In the Introduction to Scriptable Objects tutorial, they claim that Scriptable Objects are amazing data containers. However, it’s not clear how useful Scriptable Objects really is, and what problems they’re trying to solve. In this article we will look at all usecases of Scriptable Objects, what issues they’re trying to solve, what the original solutions are, and what the pros and cons of each approach are.

Overall

What is a Scriptable Object

Data Container
Can NOT be attached to GameObject/Prefab
Can be serialized and inspected like MonoBehaviour
Can be put into .asset file

Pros

Built into Unity
Can be saved as assets
Can save during runtime
Can be referenced instead of copied like MonoBehaviour
Internal solution (no files/parsing). Performance is quite fast.
Add to structure as you go. No need to go through a large file/multiple files to replace schema.

Cons

Requires Editor Scripting
Can’t edit outside Unity
Can’t save once deployed
Cannot optimize loading speed since this is Unity code

Use case 1: Global Game Settings

Every game has global settings for various aspects such as: Sounds, Video, Game play. There are some options to store these settings:

Scattered throughout the code, or maybe centralized into one source file.
1. Pros: Easy to code
2. Cons: Designers cannot find these settings easily. Change cannot persist if you quit Play mode
Stored in config files: text/binary.
1. Pros: Easy to code. Designers can look at them if they’re text files.
2. Cons: Cannot change settings while playing. Might be hard for designers to understand and change the settings files since there’s no validation method.
Stored in Prefabs
1. Pros: Prefab can be stored as assets
2. Cons: It might be too heavy for pure data purpose. Duplicate memory if you create instance.

ScriptableObject can be used to store global settings in .asset files.

Pros
1. Easy to find them in Unity
2. Easy to change and test
3. Can change while playing. Changes persist after quitting play mode
4. Can have custom editor so it’s easy to note the meaning of each field
5. Can be validated using custom editor code.

Implementation

Create a base class for all the global game Settings. It will have a static property Instance, which provides a way to create a singleton instance in a fixed location. This location will be customized on a project basis.

1
2
3
4


public class Setting<T> : ScriptableObject where T : Setting<T>
{
...
}

Create subclass the Setting class. Provide a MenuItem for accessing it.

1
2
3
4
5


[MenuItem ("Settings/TextureSetting")]
public static void Edit ()
{
 Selection.activeObject = Instance;
}

Use case 2: Swappable Global Game Settings or Scene Settings

Sometimes we don’t want to have to change some global settings back and forth between a set of parameters since it’s very time-consuming. So we might want to store several pre-defined settings and swap between them quickly.

Another case is scene settings. These settings only affect the scene, not the whole game, and they usually change between scene reload, for instance, game mode settings: Easy, Medium, Difficult.

ScriptableObject can deal with this situation:

To be able to swap setting, create a wrapper setting which references the specific setting
To swap scene setting, simply load the specific setting in Assets then assign it to specific field in a MonoBehaviour

Implementation

Create multiple settings
Define a field in MonoBehaviour or parent ScriptableObject, referring to the settings ScriptableObject

Use case 3: Scriptable Objects as MasterData or Item Database

For any sufficiently large game, the game data will be so big that you have to separate them from the code, and they will be referred to as MasterData.

Popular solutions for storing MasterData include:

Text/Binary files. E.g Unity XML Tutorial
Database
Network

Cons

One common disadvantage with these approach is you will need an external viewer to be able to see and modify masterdata conveniently.
You will have to replicate the schema in code

ScriptableObject can offer a way to create and edit masterdata inside Unity Editor.

ScriptableObject Pros

Can have references to Resources
View, Add, Delete and Edit entities/items conveniently in Unity Editor
Use ScriptableObject directly in MonoBehaviour instead of having to create an additional layer of MonoBehaviour

Implementation

Introduction to Scriptable Objects shows how you use Scriptable Object to create and edit Inventory Lists.

Saving Data in Unity: ScriptableObjects shows how you can create multiple Enemy ScriptableObject and use them in the EnemyMove MonoBehaviour.

Use case 4: Scriptable Objects as Dynamic Behaviour

Another usecase of ScriptableObject is using them as game behaviour which has data that can be modified by designer. They have some instance functions, like MonoBehaviour, but unlike MonoBehaviour which cannot be saved independently without prefabs, ScriptableObject can be saved as if they’re just pure data. Game programmers can change the code of the behaviour without affecting game designers.

Implementation

These ScriptableObjects are similar to the ones in Usecase 3, but they have functions which can act arbitrarily on GameObject, MonoBehaviour and so on.

Ability System with Scriptable Objects shows how you implement an Ability System, where Ability is ScriptableObject with its own behaviour functions.

The Ability class contains data and abstracts methods which act on GameObject based on those data.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


public abstract class Ability : ScriptableObject
{
 public string aName = "New Ability";
 public Sprite aSprite;
 public AudioClip aSound;
 public float aBaseCoolDown = 1f;

 public abstract void Initialize (GameObject obj);
 public abstract void TriggerAbility ();
}

The ProjectileAbility is a concrete Ability subclass, which modifies the target GameObject as needed and trigger the projectile action.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


using UnityEngine;
using System.Collections;

[CreateAssetMenu (menuName = "Abilities/ProjectileAbility")]
public class ProjectileAbility : Ability
{
 public float projectileForce = 500f;
 public Rigidbody projectile;

 private ProjectileShootTriggerable launcher;

 public override void Initialize (GameObject obj)
 {
 launcher = obj.GetComponent<ProjectileShootTriggerable> ();
 launcher.projectileForce = projectileForce;
 launcher.projectile = projectile;
 }

 public override void TriggerAbility ()
 {
 launcher.Launch ();
 }
}

ScriptableObjectDemo is a more comprehensive demo.

Other notes

MasterData can include global settings, constants and any kind of game data. This really depends on the developers/designers to choose.
ScriptableObjects can help you to load some specific items in an Item Database quickly, if the items are stored as individual assets. Refactoring multiple ScriptableObject assets into a collection is simple.

Other Methods to store data

From source code
1. A lot of code for storing data
2. Large binary size
From GameObject
1. We can store data in Component inside Prefabs, or in Scene.
2. This way is mostly heavier than ScriptableObject
3. However, you can pack multiple Component arbitrarily so it might be helpful.
From XML, JSON, CSV, Excel
1. Cannot have resources reference
2. Might be good to have a workflow to convert into ScriptableObject
3. To update data in saved data, text/binary are more suitable than ScriptableObject, which cannot be saved once deployed.
PlayerPrefs
1. Can be used to save data
2. Not suitable for very large amount of data
3. Cannot control the save process easily
From embedded DB
1. Cannot have resources reference
2. Might be good to have a workflow to convert into ScriptableObject
3. To update data in saved data, database is very convenient. But we must care about performance.
4. We must be aware of encryption capabilities of the DB.
From Network
1. Cannot have resources reference
2. Usually used in combination with a text/binary persisted in local storage
3. To update data via Network with ScriptableObject, AssetBundle is needed. So the general-purpose text/binary format might be better.

References

Understanding Reactive

Sun, 04 Dec 2016 00:00:00 +0700

Reactive tutorials and manual

The introduction to Reactive Programming you’ve been missing Best introduction tutorial to Reactive Programming

Introduction to Rx This book aims to teach you:

about the new types that Rx will provide
about the extension methods and how to use them
how to manage subscriptions to “sequences” of data
how to visualize “sequences” of data and sketch your solution before coding it
how to deal with concurrency to your advantage and avoid common pitfalls
how to compose, aggregate and transform streams
how to test your Rx code
some guidance on best practices when using Rx.

ReactiveX The home of ReactiveX. Introduction, All operators are illustrated with graphical marble diagrams, there makes easy to understand

Reactive Design Patterns

Reactive Design Patterns by Dr. Roland Kuhn: leader of Typesafe’s Akka project, and coauthor of the book Reactive Design Patterns and the Reactive Manifesto. Roland highlighted the importance of making reactive software: of considering responsiveness, maintainability, elasticity and scalability from the outset of development. He explored several architecture elements that are commonly found in reactive systems, such as the circuit breaker, various replication techniques, and flow control protocols. These patterns are language-agnostic and also independent of the abundant choice of reactive programming frameworks and libraries.

Reactive Design Patterns by Roland Kuhn and Jamie Allen

Reactive usecases

Bacon.js introduces FRP concepts and benefits with Bacon.js, an FRP library for both browsers and server-side JS

Immutability, interactivity & JavaScript Surprisingly the high performance mutation available in modern JavaScript engines is a great foundation for building high performance immutable collections. Even more surprisingly efficient immutable collections permit new ways of approaching user interface programming. While the details will be in Om, an immutable user interface toolkit written in ClojureScript over Facebook’s React, the talk will be primarily focused on high level concepts easily ported to JavaScript. We’ll dive in and see how trees of JavaScript arrays can permit building these efficient immutable collections. Then we’ll see how embracing immutable values dramatically simplifies some classic hard problems in client side programming including but not limited to undo, error playback, and online/offline synchronization.

What does it mean to be Reactive The inimitable Erik Meijer delivering his opening keynote to React 2014

Unity Texture compression and optimization

Sat, 03 Dec 2016 00:01:00 +0700

A common question when building Unity games is which texture compression format will be the best. The criteria are: size on disk, memory footprint, performance.

We have many options in the Unity Engine: ETC1, ETC2, DXT3, DXT5, and so on. How do we choose? Let’s look at some optimization tricks to see how others choose their formats.

First you need to understand How much memory does a texture take up on the GPU?

many modern engines opt to store the same format on disk as they do in memory, leading to files that are the same size as the texture’s memory requirements
Uncompresed image of 256x256 is 256KB. A DXT1 image of 256x256 is 32KB. And DXT3 or DXT5 is 64KB
http://mainroach.blogspot.com/2014/03/the-png-vs-gpu-battle-on-android.html also explains why you don’t want to use plain png textures. Instead, export them to DXT1, PVR or ETC

Efficient Game Textures with Hardware Compression examines preferable compression formats which are supported on the GPU to help you reduce .apk size and loading times of your game:

As you can see, with higher OpenGL support you gain access to better formats. There are proprietary formats to replace ETC1, delivering higher quality and alpha channel support. These are shown in the following table:
- ATC Available with Adreno GPU.
- PVRTC Available with a PowerVR GPU.
- DXT1 S3 DXT1 texture compression. Supported on devices running Nvidia Tegra platform.
- S3TC S3 texture compression, nonspecific to DXT variant. Supported on devices running Nvidia Tegra platform.
Using hardware accelerated textures in your games will help you reduce the size of your .apk, runtime memory use as well as loading times.

Unity 2D Texture Optimization explains how they group textures by type instead of logical groups to save memory:

2048x2048 sprite sheet above, even with compression applied, took up 4mb in Texture2D memory
assets fail to render and appear like black shapes
organize sprite sheets into three compression types: Solids, Fades, and Alpha Punchouts.
Solids are any rectangular assets with NO alpha. Here we can get a major savings by selecting a 4-bit compression that doesn’t support alpha.
Alpha Punchouts are any other shapes that use binary alpha, meaning the area of the image is either 100% or 0% alpha. Here we select a 5-bit compression
Fades are reserved for our most complex objects that contain variable degrees of alpha. We use these sparingly and compress them using a minimum of 8-bit RGBA to look best.

ETC1 vs ETC2 vs DXT5 discuss which is the best texture format

ETC2 only for devices supporting ES 3.0
But if your targeting all devices… which u should consider doing in 2015, then it doesnt matter if you pick ETC2 or DXT5 Crunched because theyre both getting decompressed. Which makes sense for ARGB. And then for RGB just ETC1
Most devices support ETC1 http://developer.android.com/guide/topics/graphics/opengl.html#textures
I was able to remove 25% of my file size this weekend, thanks to switching to ETC1 + DXT5 Crunched

Android Texture Compression - a comparison study with code sample compares the quality and sizes of different formats on Android devices including: png, etc, etc2, pvrtc and s3tc.

ETC2 as default texture compression on Android discuss usage of ETC2 format

We use DXT5 on our sprites to save space on apk file. When the device does not support your texture type, Unity uses software decompression on load and your textures become 32bit RGBA.
Use ETC2 to save memory. It might be bad for some low-spec device if they don’t support ETC2. Also one more reason to pack your own sheets instead of using Unity packer, since you can do dithering yourself

Some texture optimization recommendations

Don’t use mipmap for 2D Is it possible to turn on Mip Maps for a sprite
Compress your textures to DXT1 or DXT5 Memory optimization tricks
What Resolution should I be painting sprites in? 2048x2048 seems a bit big already on mobile device

How Can I Add Alpha To ETC1 Compression? attempts to answer the question about ETC1 + Alpha channel

Sprites placed on some atlas by specifying them with a packing tag
Make sure to mark the Override for Android checkbox as well as the Compress using ETC1 checkbox. Unity will split the resulting atlas into two textures, each without Alpha and then combine them in the final parts of the RenderPipeline.
The UI shaders in Unity 5.3.0 and earlier do not support ETC1 + Alpha
Yes. The UI elements do not work well with ETC1. We have a bug on it. (http://forum.unity3d.com/threads/etc1-alpha-feature.350184/)

Unity mobile Splitalpha. This blogs has solved the issue with ETC1 + Alpha and provided a solution for both Android and iOS devices.

ETC1 with Alpha channel splitalpha
- Split Alpha texture

1
2
3
4
5
6


 合計サイズ (MiB) RGBA 16bit 比のサイズ削減率 (%)
RGBA 16bit	 879	 0
RGBA PVRTC 4bit	 229	 74
RGBA ETC2 8bit	 431	 51
Split Alpha (Android)	249	 72
Split Alpha (iOS)	 272	 69

https://github.com/keijiro/unity-alphamask

In conclusion, use ETC + Alpha channel whenever you can because it provides the best build size and memory footprint in most cases, at reasonable quality.

Unity geometry distortion on child object

Sat, 03 Dec 2016 00:00:00 +0700

In Unity there is a geometry issue with the child object of non-uniformly scaled parent. When the parent object does not have (1,1,1) scale, then the child object will be skewed weirdly when they rotate. This issue has been mentioned in the below references:

The solution is to:

Make the parent uniform, OR
Child the objects to another uniformly scaled parent

Scale Shuriken Particle System

Tue, 29 Nov 2016 00:00:00 +0700

Unity does not provide a way to scale Shuriken particle system in Editor. The process to scale each particle system manually is very inconvenient.

There are some plugins on the Asset Store which can help you with this tasks:

I’ve also written a tool to scale Shuriken Particles in the Editor: unity-particle-scaler. It’s very convenient and simple to use.

Unity Asset Bundle

Tue, 29 Nov 2016 00:00:00 +0700

Asset Bundle is a big topic in Unity. Initially, you want to grasp the basic setup and make something work. As your games get bigger, you might want to do more customization to make sure you have full control of the lifecycle. Here are some documents I’ve studied while learning about asset bundle. Ultimately, my goal is to make a full asset bundle workflow for big online game, so this blog will be a work in progress until I can transfer it into a working repository.

Asset bundle and AssetBundleManager

AssetBundles and the AssetBundle Manager
- AssetBundles are downloaded and cached in their entirety.
- AssetBundles do not need to be loaded in their entirety.
- Assets in AssetBundles can have dependencies on other assets.
- Assets in AssetBundles can share dependencies with other assets.
- Each AssetBundle has some technical overhead, both in the size of the file and the need to manage that file.
- AssetBundles should be built for each target platform.
The steps of working with AssetBundles in the editor fall roughly into these steps:
- Organizing & Setting-up AssetBundles in the editor.
- Building AssetBundles.
- Uploading AssetBundles to external storage.
- Downloading AssetBundles at run-time.
- Loading objects from AssetBundles.
Using Asset Variants to support different resolution
- Create Variants folder
- Create corresponding SD and HD folder (must be same structure)
Pack sprites into AssetBundle
- Use packing tag normally. Remember to set Sprite Mode: Single. Then set the AssetBundle
Load sprite sheet from Asset Bundle
- Can load Sprite or Texture2D, but it can’t load Sprite from a SpriteSheet directly
- http://forum.unity3d.com/threads/packing-a-texture-sprite-sheet-in-an-asset-bundle-with-already-sliced-subtextures-possible.313186/
- Basically use LoadAssetWithSubAssets
Issues
- No subfolder inside AssetBundle
- Clear cache in ~/Library/Caches/Unity/ http://www.leandro.co.uk/unity/caching-assetbundles-in-unity/
- Loading prefabs with script references from assetbundle
  - http://answers.unity3d.com/questions/1032495/loading-prefabs-with-script-references-from-assetb.html
- Variants with prefab
  - http://forum.unity3d.com/threads/official-how-did-asset-bundle-variant-fail-to-satisfy-your-hd-sd-use-case.375716/
- Bundles have to be updated across unity version: http://forum.unity3d.com/threads/end-of-the-resources-folder.363800/
  - Or force player to update their client
  - Client has to update and redownload ALL bundles

AssetBundle usage patterns

If an AssetBundle is unloaded improperly, it can cause Object duplication in memory
Most projects should use AssetBundle.Unload(true) and adopt a method to ensure that Objects are not duplicated
AssetBundle.CreateFromMemory
- loads an AssetBundle from a managed-code byte array (byte[] in C#)
- If the AssetBundle is LZMA compressed, it will decompress the AssetBundle while copying
- Uncompressed and LZ4-compressed AssetBundles will be copied verbatim
- The peak amount of memory consumed by this API will be at least twice the size of the AssetBundle: one copy in native memory created by the API, and one copy in the managed byte array passed to the API
- Assets loaded from an AssetBundle created via this API will therefore be duplicated three times in memory
AssetBundle.CreateFromFile
- If the AssetBundles are uncompressed or LZ4
  - On device: only load the AssetBundle’s header. Objects are loaded on-demand. No excess memory will be consumed.
  - On Editor: load the entire AssetBundle into memory
- Calls to AssetBundle.LoadFromFile will always fail for LZMA-compressed AssetBundles.
WWW.LoadFromCacheOrDownload
- WWW object will keep a full copy of the AssetBundle’s bytes in native memory
- 3 ways to avoid
  - Keep AssetBundles small
  - If using Unity 5.3 or newer, switch to using the new UnityWebRequest API’s DownloadHandlerAssetBundle, which does not cause memory spikes during downloads.
  - Write a custom downloader. For more information, see the Custom downloaders section.
  - Write a custom downloader
AssetBundleDownloadHandler
- LZMA-compressed AssetBundles will be decompressed during download and cached uncompressed.
- does not keep a native-code copy of all downloaded bytes
- supports caching in a manner identical to WWW.LoadFromCacheOrDownload
Examples of situations which may prevent the use of UnityWebRequest or WWW.LoadFromCacheOrDownload:
- When fine-grained control over the AssetBundle cache is required
- When a project needs to implement a custom compression strategy
- When a project wishes to use platform-specific APIs to satisfy certain requirements, such as the need to stream data while inactive. Example: Using iOS’ Background Tasks API to download data while in the background.
- When AssetBundles must be delivered over SSL on platforms where Unity does not have proper SSL support (such as PC).
AssetBundles in the caching system are identified only by their file names
LZ4 decompress individual Objects without needing to decompress the entire AssetBundle

Asset Bundle Compression

Unity AssetBundle summary

[Unite Japan 2013] Scene / Memory / Asset Bundle
- 【process】
  - ① Build the asset bundle (A).
  - ② Download the asset bundle (A).
  - ③ Load the asset bundle (A).
  - ④ Load the asset (B) from the asset bundle.
  - ⑤ Generate an instance (C) of the asset.
  - ⑥ Unload the asset bundle (A).
  - (Note that unloaded assets can not depend on other assets)
  - ⑦ Discard instance (C).
  - ⑧ Unload asset (B).
- AssetBundle placement place】
  - ① Server
  - ② In the StreemingAsset folder
- Minimize size of AssetBundle】
  - ① It does not depend on others (Include all referenced assets in AssetBundle.)
  - ② It depends on in-app scripts and basic components.
  - ③ It depends on another AssetBundle.
- 【Correspondence by Platform】
  - ① Editor (If you are looking at bundled assets bundle, it will be difficult to test, so let’s do something.)
  - ② Android
  - ③ IOS
- 【How to Load Asset Bundle】
  - ① Use the cache. ‘WWW.LoadFromCacheOrDownload’
  - (Note: 150 days deletion and caching can not be deleted.)
  - ② One time only “WWW (” http: // … “), WWW (” file: // … “)”
  - ③ Save locally and do not use cache. “AssetBundle.CreateFromFile, AssetBundle.CreateFromMemory”
- Supplement 1: How to summarize asset bundles
  - ① Compressed or uncompressed
  - ② Individual or large quantity
- Supplement 2
  - ① Individual synchronous load
  - ② Individual asynchronous load
  - ③ bulk synchronous load
- 【Efficient Build】
  - ① Automation
  - ② Folder structure
  - ③ Adjustment of property at build time · · ·
  - (Side street: property adjustment at asset import)
- 【Correspondence at the time of version up】 · · · I do not use it so I omit it
  - ① Cash on the URL
  - ② Compatibility
- 【Others】 · · · I do not use it so I omit it
  - ① To use binary data.
  - ② Include the script in the asset bundle. (It is impossible in IOS, so it is omitted)

Game backends

Fri, 25 Nov 2016 00:00:00 +0700

Top 10 Parse Alternatives For Your Game Backend

GameSparks
PlayFab
HeroicLabs
Gamedonia
Kii
Kinvey
BrainCloud
GamuaFlox
App42
Photon

Why should you use GameSparks

GameSparks vs PlayFab vs Firebase

Writing Unity iOS plugin

Fri, 25 Nov 2016 00:00:00 +0700

Building Plugins for iOS is a guide from Unity.

Two approaches

Approach 1: Put plugin source code .mm,.c,.cpp files in Assets/Plugins/iOS folder.
Approach 2: Build plugin library to .a file then put it in Assets/Plugins/iOS

How to build Unity3d Plugin for iOS experience from a developer

Plugin for Unity and iOS iOS plugin with source code inside Asset folder

Unity3D Plugins Development Guide

How to do blur effect in Unity

Thu, 24 Nov 2016 00:00:00 +0700

Image Blur

can use a camera which render to a rendered texture
add the images to be rendered to a second canvas, which uses the new camera with screenspace-camera
Add blur shader to the Camera, or a parent object which contains all images
Add the rendered texture to anywhere you like in the first camera

Dynamic Background Blur

Blur Behind Window Use Camera post effect
Dynamic Blurred Background on UI Use Grabpass
http://blog.ivank.net/fastest-gaussian-blur.html

Unity local network multiplayer

Mon, 21 Nov 2016 00:00:00 +0700

iOS device can connect to iOS device via Bluetooth using:

Android device can connect to Android device via Bluetooth using:

Android Bluetooth Multiplayer (Pro)

https://github.com/DarkRay/Unity3D-bluetooth A low level bluetooth library.

Android and iOS cannot connect to each other via iOS as mentioned here.

Unity3D for iOS and Android: Multiplayer. Options for multiplayer game

via Bluetooth (using Prime31 plugin)
- iOS
via LAN (using Unity RPC) The players can start combats in a Local Area Network with any of above devices: iOS vs iOS, iOS vs Android, Android vs Mac, and so on.
- iOS
- Android
- Mac
- Web (Kongregate)
via Game Center (using Prime31 plugin): Uses the Game Center multiplayer to match combats.
- iOS
via Global Server (an in-house solution): The players can start combats around the world with any of above devices: iOS vs iOS, iOS vs Android, Android vs Mac, and so on.
- iOS
- Android
- Mac
- Web (Kongregate)

UNET the new Unity Networking library.

TNET Another option which uses UDP for multiplayer game.

Alljoyn makes it easy for devices to communicate. Unfortunately it does not support Unity.

Setting sorting layer and order in layer of Mesh Renderer

Sun, 30 Oct 2016 00:00:00 +0700

Unity 5.x exposes the sorting layer and order in layer of SpriterRenderer, but not MeshRenderer. Fortunately, it’s very easy setting these property of the MeshRenderer in code. I’ve created a simple solution for setting sorting layer and order in layer of any Renderer component using a simple component called SortingLayerSetter.

It looks like this in the Editor

When to use Script Execution Order

Fri, 28 Oct 2016 00:01:00 +0700

Normally we don’t control the execution order of MonoBehaviour scripts, and we should not. However, there are cases where we do want some scripts to be executed before others. Some usecases include:

A Controller script that should be executed as the entry point to the scene
Scripts which use LateUpdate and must be executed in specific order

For these cases, we will assign an integer number to those scripts in Edit > Project Settings > Script Execution Order. It’s best practice to use large and discrete number such as 100, 200, -100 instead of 1, 2, 3 because it would make it easier to insert something in between them when we need to.

One inconvenience with Unity Editor GUI for Script Execution Order is that it’s a bit hard to find your classes when there are a lot of them. The solution for this is to add Script Execution Order as meta information to the class using attribute. There’s already an implementation for this: https://github.com/kwnetzwelt/ugb-source/blob/UGB-3.0/UnityGameBase/Core/Editor/GameScriptExecutionOrder.cs and https://github.com/kwnetzwelt/ugb-source/blob/UGB-3.0/UnityGameBase/ScriptExecutionOrderAttribute.cs. Using these 2 classes, now we can add Script Execution Order to any class as follows:

1
2


[ScriptExecutionOrder(-1000)]
public abstract class Game : MonoBehaviour

Run specific code when Editor starts

Fri, 28 Oct 2016 00:00:00 +0700

Sometimes we want to execute code whenever we hit Play button in Unity Editor. The reason for this usually is that we want to enforce some workflow automatically such as getting specific environment information (e.g. git hash, date) and fill it in a prefab or something. We could do these things by creating a Custom Window with a button somewhere, but it feels too manual.

Fortunately, Unity has offered a simple way to do this, that is InitializeOnLoadAttribute.

http://blog.andreimarks.com/2012/08/16/unity-how-to-run-specific-code-only-when-building-out-a-project/ shows an usecase of InitializeOnLoadAttribute: to generate a tracking tag of the build with the build date.

Beware of a potential problem here

An awesome review of other ways to execute code on startup are listed here http://www.codingjargames.com/blog/2015/08/04/unity-and-initialization-order/

MVC in Unity

Thu, 27 Oct 2016 00:00:00 +0700

Some MVC like frameworks in Unity

Key Value Observing This is a simple implementation of MVC according to his own understandings

Karma Lightweight MVC framework using Zenject DI container. It is inspired from MODEL VIEW CONTROLLER PATTERN FOR UNITY3D USER INTERFACES

Marklight Looks nice. It offers XUML and external editor which might be good for view management, but it also feels too restrictive because you have to follow their way.

Unity3d.UI.Windows Uses a Window system to create UI and layout elements. Try doing too many things: Audio, Tweening

strangeioc Obsolete and not maintained

uFrame MVVM It’s trying to do too much by offering a graphing/diagramming engine and code generation. I really don’t like code generation

Discussion

It looks like the main advantages of using these MVC frameworks are:

Some of them can support theme change
They have some existing controls so you don’t have to implement yourself.

However, there are several disadvantages:

If you don’t need to change theme then definitely you don’t need to separate View and ViewModel or Presenter.
UI usually consists of a big container and a lot of smaller views. Testing small views is easy so you don’t need to create separate View class for each. Testing the container is complicated, you want to do it with a test scene in Unity anyway, thus there’s no need to try to make an ViewModel interface for testing.
The examples of Unity MVC implementation in some blogs are usually naive and contrived. As such, they don’t scale when you have really complex UI. In addition, they usually confuse between UI and gameplay, so they take example such as hitting enemies or updating their HP bar. MVC is suitable for UIs and maybe some turn-based gameplay, but extending it to a fighting gameplay requires much more than some optimistic guesswork.
Controller needs to behave according to states, that makes the ViewPresenter or ViewModel also have to replicate those states fully or partly. It’s quite difficult to know which should be the common behaviour. A simpler way is to just merge Controller and View/ViewPresenter/ViewModel.

Understanding Promises

Wed, 26 Oct 2016 00:02:00 +0700

Understand promise vs callback The ABCs of promises

Promise nuggets More examples of promises

Why I am switching to promises A guy switches from callbacks to promises.

We have a problem with promises Promises are not so easy to use if you don’t know exactly how to use them properly. Try to avoid the mistakes of using something without fully understanding it.

Retry patterns Several patterns of retry in promises

promise-retryer Another way to do retry with promise which supports * custom delays based on attempts * maxRetries * promise result validation (if it fails then keep trying)

Building social networks

Wed, 26 Oct 2016 00:01:00 +0700

How To Build An Online Community: The Ultimate List Of Resources

CommunitySpark

How to Build a User Community

25 Ways to Build Your Community

The Art of Creating a Community

Building an Online Community: Just Add Water

The power of checklist

Mon, 10 Oct 2016 00:00:00 +0700

Why

The world has become more complex
Our brain has not changed much

Examples

Checklists in aviation help alleviate accidents
Checklists in construction makes the failure list very low

Benefits

Checklists verify that the necessary minimum gets done Because sometimes the most important stuff is the simple ones.
Checklists free up mental RAM Checklists don’t replace judgment, they enhance it.
Checklists instill discipline and increase the chance of stuff getting done.
Checklists save time because you spend less time fixing simple mistakes.

How

Investigate your failures and look for “killer items.” Look for failure or friction points in the tasks you do routinely
Focus only on the “stupid” essential stuff that’s frequently overlooked or skipped Just focus on putting down the “stupid” but essential stuff that you frequently miss. Your checklist should have no more than 9 items on it.
Decide if you need a “communication” checklist Most checklists are likely procedural (they lay out things you need to do), but some tasks or projects are so complex that communicating with others becomes vital to managing all the moving pieces. In such a case, create a dedicated communication checklist and make sure it includes who needs to talk to whom, by when, and about what.
Decide if your checklist will be a “DO-CONFIRM” or “READ-DO” checklist. With DO-CONFIRM checklists, you do your job from memory and experience, but then at a certain point you stop to go through your list to verify you did everything. READ-DO checklists require you to read and perform a task on the checklist before you can move to the next task. If you need more flexibility, go with DO-CONFIRM; if you need more exactness go with READ-DO.
Test your checklist in the real world and refine as needed. If you’re still experiencing the same failures or if the checklist makes work cumbersome to the point that it becomes a stumbling block, then you need to refine your checklist.

References

The Power of Checklists

Generate one-time password from the command line

Sun, 02 Oct 2016 00:00:00 +0700

One-time password is pretty common these days for any type of account that offers two-factor authentication. We can use an app to generate OTP but it would be troublesome if we lost the app or the phone. Fortunately there’s a simple way to generate OTP programmatically using libraries such as Python OneTimePass.

First, install OneTimePass with pip:

1

pip install onetimepass

Then you get the secret generated from the service provider you’re using. Normally it would be a time-based token, such as the ones you use for Google Authenticator.

To get time-based token you invoke it like this:

1
2
3
4
5


import onetimepass as otp

my_secret = 'MFRGGZDFMZTWQ2LK'
my_token = otp.get_totp(my_secret)
print my_token

Remember to store your secret safely.

Unity singleton

Thu, 29 Sep 2016 00:00:00 +0700

First of all, please remember that Singletons are generally not recommended due to various obvious disadvantages:

Hard to reason about code
Encourage coupling
Potential concurrency issue

However, in game development it’s super useful to have singleton for many types of global system, including but not limited to:

Sound system
Time manager
Localization
Tutorial
Login
Global Notifier

In this article we will look at some options of Singleton implementation we have in Unity to see what problems they’re trying to solve and what assumptions they made.

Requirements

Let’s first review some requirements for a useful singleton system in Unity.

Singleton class types

MonoBehavior based: These types of singletons extends MonoBehavior and shows themselves in the scene hierarchy so that you can look at their exposed members. Another reason is you want them to have an Update function to do something useful in it.
Non MonoBehavior based: Traditional singletons in any OO languages. These singletons don’t need to be inspected in the scene nor do they need Update. We will not focus on these types of singletons.

Singleton lifecycle types

Has dependencies: These singletons depend on other system or singletons to exist before they can start
No dependencies: These singletons can be created anytime without waiting for any other entities.

Singleton configurability types

Has customized parameters: This is a bit overlap with Has dependencies singletons. These singletons might: 1. Depend on parameters provided by another system, such as the FileSystem to load certian parameters from disk. OR 2. Need customized parameters or linked prefab. They might be in a prefab themselves such as a LevelManager.
No customized parameters: These singletons behave the same all the time.

Solutions

Fortunately there’re already some solutions written in unity3d so we can review and improve them as we wish.

AManagerClass

AManagerClass is a standard implementation which supports MonoBehavior-based singletons. In the code, we refer to the singleton like this:

1

 AManager.instance.Foo ();

The instance function implementation is as below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


 public static AManager instance {
 get {
 if (s_Instance == null) {
 // This is where the magic happens.
 // FindObjectOfType(...) returns the first AManager object in the scene.
 s_Instance = FindObjectOfType(typeof (AManager)) as AManager;
 }

 // If it is still null, create a new instance
 if (s_Instance == null) {
 GameObject obj = new GameObject("AManager");
 s_Instance = obj.AddComponent(typeof (AManager)) as AManager;
 Debug.Log ("Could not locate an AManager object. \ AManager was Generated Automaticly.");
 }

 return s_Instance;
 }
 }

There are several problems with AManager:

We have to duplicate it for all singleton class
It’s slow due to the 2 checks

Surely we can do better!

AutoSingletonManager

AutoSingletonManager solves the code duplication problem of AManager

Here’s the main code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51


public abstract class AutoSingletonManager : MonoBehaviour { }

public abstract class AutoSingletonManager<T> : AutoSingletonManager where T : AutoSingletonManager
{
 private static bool Compare<T>(T x, T y) where T : class
 {
 return x == y;
 }

 #region Singleton

 private static T _instance = default(T);

 public static T Instance
 {
 get
 {
 if (!Compare<T>(default(T), _instance)) return _instance;

 InitInstance(true);
 return _instance;
 }
 }

 #endregion

 public void Awake()
 {
 InitInstance(false);
 }

 public static void InitInstance(bool shouldInitManager)
 {
 Type thisType = typeof (T);

 _instance = FindObjectOfType<T>();

 if (Compare<T>(default(T), _instance))
 {
 _instance = new GameObject(thisType.Name).AddComponent<T>();
 }

 //Won't call InitManager from Awake
 if (shouldInitManager)
 {
 (_instance as AutoSingletonManager<T>).InitManager();
 }
 }

 public virtual void InitManager() { }
}

The code uses recursive generic definition. This allow us to reuse code by inheriting from the singleton class as well as from MonoBehaviour. Note that we don’t have to make AutoSingletonManager<T> inherits from AutoSingletonManager, instead we can make it inherit from our own class which in turn inherits from MonoBehavior.

It supports initializing the instance from Awake so maybe it can be used by adding directly it to an object in the scene. However, InitManager is not called in Awake so if you call AutoSingletonManager.Instance after it already awakes then InitManager will never be called.

Another more subtle draw back is it uses an unnecessary comparison if (!Compare<T>(default(T), _instance)) return _instance; in the Instance property, so it’s not optimal if you call Instance in a Update loop or something similar.

Surely we can do better than this.

Secure UnitySingleton

SecureUnitySingleton is the last one of the three singleton implementation in unity3d. It has a very clear idea about the usecases of singletons. There are 3 main supported usecases:

Exists In Scene: Searches the current scene for an object with the singleton component attached to it.
Loaded From Resources: This type creates an instance of a prefab with the singleton component attached to it from a Resources folder.
Create on New GameObject: This type creates a new GameObject and attaches a new instance of the singleton component to it.

There are several issues with approach:

Even though the code is quite functional, it still suffers the performance penalty from checking too many things in the Instance property.
Lack of lifecyle methods. Even though it provides a static DeleteInstance method, there’s no other methods to execute when the instance is created. You might think that Awake can be used for that purpose, but it not explicit enough that Awake is called immediately after Instance is called. Another possible issue is Awake will not be called when the prefab is disabled, which should never be desirable but can happen due to a mistake from the developers.

This is quite good but surely we can do better.

Discussions

First of all, we realize that non of the above methods take into account concurrency issue. If we care about concurrency we can do something like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


 public class MySingleton ...
 {
 static MySingleton _instance = null;
 static object singletonLock = new object ();

 public static MySingleton Instance
 {
 get {
 if (_instance != null) {
 return;
 }

 lock (singletonLock) {
 if (_instance != null) {
 return _instance;
 }

 var singletonGameObject = new GameObject ("MySingleton");
 GameObject.DontDestroyOnLoad (singletonGameObject);
 _instance = singletonGameObject.AddComponent< MySingleton > ();

 ... other initialization code
 }

 return _instance;
 }
 }

By using a simple double lock pattern, we seemingly solve the “concurrency problem”. The question is: Do we need to?. Why you have the concurrency problem with singleton? It’s because you want to lazy load the singleton, i.e. only create it when it is used for the first time. But that’s exactly what we want to avoid if we want to achieve smooth gameplay. So what you should do instead is just create the bloody singleton at the beginning and forget about it. Remember, preload is better than lazy load.

Secondly, I’ve already mentioned the check for null is redundant if we know we only call the singleton after it’s been initialized. In the usecases listed by SecureSingleton, we see that the singleton is either created by code or already exists in the scene as a GameObject which is supposed to be configured by designers. In either case, the code to initialize the scene should be a good place for calling the initialization code of the singleton and there’s no need for making it sooner.

So what will happen if the Instance property is called before you initialize the singleton? Obviously an exception will be thrown and this is an ideal case for using Unity Assert because you will have a nice message in development mode but you can also turn it off in production build.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


	public class GameSingleton<T> : MyBaseBehaviour where T : GameSingleton<T>
 {
 ...
 public static T Instance
 {
 get {
 Assert.IsNotNull (instance);
 return instance;
 }
 }

Note that MyBaseBehaviour class is a class derived from MonoBehaviour and is customized specifically for our game. For instance, it might have general code for handling Update or OnDestroy.

All that is left now is writing a function CreateInstance for creating the singleton. This function should be called once only at the exact place where you want it. This means we should design it in such a way to discourage it from being called multiple times randomly by some careless developers. Calling CreateInstance twice should throw an exception. This is better than mindlessly guard the function in the name of “defensive programming”. It will look something like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


		public static T CreateInstance()
		{
 Assert.IsNull (instance);

			GameObject go = new GameObject(typeof(T).Name);
			instance = go.AddComponent<T>();
			instance.OnCreated();
			DontDestroyOnLoad(go);

			return instance;
		}


		protected virtual void OnCreated()
		{
		}

Here we have a virtual function OnCreated waiting to be overriden in subclass. To destroy the singleton, we don’t have to use fancy static function DeleteInstance, instead we can just get the singleton gameobject and destroy it like this:

1

 GameObject.Destroy (MySingleton.Instance.gameObject);

When the OnDestroy function is called, we will set instance variable to null then allow subclass to do cleanup themselves. The reason why we don’t use DeleteInstance is because we don’t want developers who use the API to think there’s anything special about destroying the singleton than just destroying the container object.

Finally, we discuss feature destroy if exists in scene. In my opinion, this feature accounts for a very small proportion of our usecases. Most of the time we have a singleton already exists in scene, or in some prefab is because we want to use Unity to store game data. But that’s should not be the main way to deal with game data. We’d better use off-unity format to store game data, like text or database. If we need to store linked resources we can use Scriptable Object. The point is to not rely too much on data stored in prefab or scene just because you want designers to change them easily, they can also change text file or database much more easily than firing up Unity. Also, merging prefab is harder than merging text data.

If you really want to use avoid duplicate singleton in scene, we can simply use this piece of code from SecureUnitySingleton:

1
2
3
4
5


	protected virtual void Awake()
	{
		if (InstanceExists && instance != this)
			Destroy(gameObject);
	}

Implementation

After we’ve considered different aspect of singletons and what our real usecases are, we finalize our own version Unity singleton as follows

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


using UnityEngine;
using System;
using UnityEngine.Assertions;

public class SimpleSingleton<T> : BaseMonoBehaviour where T : SimpleSingleton<T>
{
 private static T instance;

 public static T Instance {
 get {
 Assert.IsNotNull (instance, "Instance is null. Please call CreateInstance first!");
 return instance;
 }
 }

 public static T CreateInstance ()
 {
 if (instance != null) {
 Assert.IsNull (instance, "Instance is not null. Please call CreateInstance once only");
 }

 GameObject go = new GameObject (typeof(T).Name);
 instance = go.AddComponent<T> ();

 instance.OnCreated ();

 return instance;
 }

 protected virtual void OnDestroy ()
 {
 instance = null;
 }

 protected virtual void OnCreated ()
 {
 }

}

Then remember to call CreateInstance when necessary and in appropriate order.

The code with a sample scene is available on github at https://github.com/minhhh/unity-singleton

Regarding the Has Customized Parameters singletons, there are some implementations of this type using Prefab to set the parameters. This method is not recommended. Instead, we can use ScriptableObject to store the parameter and let the Singleton read from these ScriptableObject. This method will make all the settings centralized in a single location.

TODO: Create SceneSingleton

Maple.js Deconstructed

Sun, 25 Sep 2016 00:00:00 +0700

Maple.js is a simple event-based multiplayer framework using Node.js

Deconstruction

Maple provides a base class for Client and Server. Your specific game code should inherit these base classes.
The supported functionality includes:
- Connect/Disconnect
- Ping server
- Handle arbitrary message
- Sync client server update tick on every frame
The problems with Maple are:
- Use Websocket, which is slow
- Require too much sync and only applicable for Round-based games.

Osmus Deconstructed

Sun, 25 Sep 2016 00:00:00 +0700

Osmus is a tech demo of a HTML5 multiplayer game inspired by Osmos.

Deconstruction

Osmus uses node.js for the server and HTML5 Canvas with Javascript on the client side. The simulation code is shared between client and server.
Regarding network, Osmus uses socket.io. Socket.io is quite stable and performant so this is ok.
The multiplayer architecture is Server/Client, with the server being the sole authority. All inputs from any client will be rebroadcast to all clients in the room. There are several problems with this approach
- Not scalable: Simply rebroadcast all messages will increase the load on the server exponentially so this is totally not acceptable. Some sort of rate limit should be applied, such as only sending messages to viewable entities.
- Sudden positional jump on client: If the client entities can move around, then client simulation. client prediction and interpolation with server states should be applied to ensure smooth movement.

Autoformat C# code from command line

Sun, 11 Sep 2016 00:00:00 +0700

We all need a tool to format code automatically according to project’s convention. Using an IDE like Visual Studio, Xamarin or MonoDevelop, we can format code easily. However, it’s not always convenient to fireup the IDE just for formatting some code, and also having a tool on the command line makes it easier to integrate with other workflows. Therefore, it’s great if we have some tool which runs on the command line to auto format our code.

Requirements

Customizable format options
Format whole directory recursively

The second requirement is relatively easy to implement if we have a tool to format a single file on the commandline because we can just use find with some filter to iteratively apply the tool to a bunch of files.

Solution 1: Astyle

Artistic Style is a source code indenter, formatter, and beautifier for the C, C++, C++/CLI, Objective‑C, C# and Java programming languages. We can download and install Astyle rather quickly without any problems on most platforms.

Installation We will use a simple script below to help us install AStyle on Mac OSX. Installation on other platforms can be done in a similar manner

Usage After we have astyle available on the command line, applying it for our project is a matter of wrapping everything in a single Make command like so

1
2
3


# Supposed our Code is in the Code folder
format:
	find Code -iname "*.cs" -not -path "Code/excludedpath/*" | xargs -n 1 -I {} bash -c "astyle --options=.astylerc \"{}\""

Remember to create a file called .astylerc and put whatever format options you want to customize for your project there.

Solution 2: NRefactory

NRefactory is the C# analysis library used in the SharpDevelop and MonoDevelop IDEs. We can write a command line client with our customized parameters and format options, which uses NRefactory internally to format code.

TODO: Write a cli using docopt

Setup Github pages as your blog

Sat, 10 Sep 2016 00:00:00 +0700

How to setup github page as your blog? It’s actually very easy, just follow the following guides

What is Medium

Thu, 03 Dec 2015 00:00:00 +0700

Medium is a web-based service that let anyone publish articles online that was founded in 2012 by 2 founders of Twitter: Ev Williams and Biz Stone. Ev Williams said Medium was “a new place on the Internet where people share ideas and stories that are longer than 140 characters and not just for friends.”

According to wikipedia, medium is a blog publishing platform. While Medium might look like a standard blogging platform, it had been “designed for little stories that make your day better and manifestos that change the world.” And yet “it helps you find the right audience for whatever you have to say.”. Also, Medium does not show articles in a reverse-chronological index of content like normal blogging platform.

Medium seems to do following:

Create a beautiful, simple blogging platform for everyone
Pay some people to post to the site, but not most of them
Promote the people they’ve paid along with a very small subset of everyone else.

Therefore the content on medium can be either be:

awesome if they were written by profesisonal writers who were hired and edited by professional editors
opposite of awesome if they were written by mediocre bloggers.

The differences between Medium and traditional publication are:

If the traditional publication publish anything bad or plagiarised, it reflects poorly on them.
If Medium publishes anything bad or plagiarised, it reflects poorly on the writers

Medium is good for you if:

You aren’t not going to blog a lot.
You like the Medium environment.
You aren’t in it for the money. Medium does have some paid contributors, but not for everyone.

REFERENCES

Setup OSX

Wed, 14 Oct 2015 00:00:00 +0700

minhhh/wiki/mac.md

An Introduction to Memcache

Sat, 10 Oct 2015 00:00:00 +0700

minhhh/wiki/memcache.md

A netcat cheatsheet

Thu, 01 Jan 2015 00:00:00 +0700

minhhh/wiki/netcat.md

An Introduction to Bash

Sun, 23 Nov 2014 00:00:00 +0700

minhhh/wiki/bash.md

A Guide to Python's Magic Methods

Sun, 19 Oct 2014 00:00:00 +0700

minhhh/magicmethods/README.md

Awk tutorial

Sun, 05 Oct 2014 00:00:00 +0700

minhhh/wiki/awk.md

Python decorator tutorial

Sun, 05 Oct 2014 00:00:00 +0700

minhhh/wiki/py_decorators.md

Android CLI tool cheatsheet

Fri, 03 Oct 2014 00:00:00 +0700

minhhh/wiki/android_cli.md

Embed git file to pelican

Thu, 11 Sep 2014 00:00:00 +0700

Writing articles in github pages is nice, because you have github repository with all the nice features for document management, however sometimes it’s not where I want my articles to reside. For instance, I want the articles about git to be in a separate git repository.

I have several solutions for this problem:

I could duplicate the article. But I won’t do this.
I could store the articles as gist like this:

[gist:id=dc8b7c536d0fe9c7003f]

But I can’t store a lot of related things in gist because that’s the role of a real git repo.

I could store the articles in the normal git repo, and embed it into the article in github page. I chose this approach for long articles. Like this:

There’s already a nice tool to do this: gist-it. Using it is really simple, just clone the repo and deploy it to an AppEngine instance. The downside of this is it does not generate html code for Markdown.

The best solution for me is to use a plugin for embedding git file into pelican like this:

minhhh/wiki/sample.md

How to rebase in Git

Tue, 09 Sep 2014 00:00:00 +0700

minhhh/git-manual/git_rebase.md

Git cheat sheet

Fri, 05 Sep 2014 00:00:00 +0700

minhhh/git-manual/README.md

Creating this blog

Sat, 07 Jun 2014 00:00:00 +0700

When creating this blog, I used the following references: