Tuxmino

Getting Started

First create your lua file. The lua file should be in the gamemodes directory. The contents of your lua file should look like this:

--[[
--
-- File: template.lua
-- ------------------
-- Author: YourName
--
-- This is a template for creating tuxmino game modes.
--
--]]

--[[ This Function gets called once when the game is loaded --]]
function start()
end

--[[ This function gets called when the game is reset or selected --]]
function reset()
end

--[[ This function gets called every frame --]]
function update()
end

--[[ This function gets called every time a piece locks to the PlayField --]]
function advanceLevel(amount, lineCount)
end

If you are sharing this game mode with others, it is recommended to fill out the docstring at the top with the filename, author, contributors, and the description of your game mode. In this tutorial we will only be using the functions start() and advanceLevel(). update() is not required and is only for advanced use cases.

start()
This function gets called once when the game is loaded, we will be using it for initializing resources and setting the intial settings of our game mode.

reset()
This function gets called when we reset or select the game. One example of its use would be to reset passed grade requirements.

advanceLevel(amount, lineCount)
This function gets called every time a piece locks to the PlayField. we will be using it to update the current level, section level, and the speed timings based on our current level. amount is the amount of levels that should be incremented and lineCount is how many lines the player scored.

Initializing Our Game Mode

First, lets start off by setting the title and frame color of our game mode, we can do this by calling initGameMode().

--[[ This Function gets called once when the game is loaded --]]
function start()
  -- Set the name of our game mode to "Tutorial" with a red frame
  initGameMode("Tutorial", 255, 0, 0)
end

If you launch the game, you should see "Tutorial" in our list of gamemodes. It should also have a red frame color. However the background is black, so lets add a background!

--[[ This Function gets called once when the game is loaded --]]
function start()
  -- Set the name of our game mode to "Tutorial" with a red frame
  initGameMode("Tutorial", 255, 0, 0)
  -- Set the number of backgrounds to two
  initBackgrounds(2)

  -- Load our two backgrounds
  initBgIdx(0, "yourbackground.png")
  initBgIdx(1, "anotherbackground.png")

  -- Set our background to the first background
  setBackground(0)
end

First we call initBackgrounds() with the number of backgrounds we want to have. If you are curious, this function is allocating an array of Textures for us in C. Then, we load our two backgrounds with initBgIdx() which takes two parameters (index of the background, and the filename of the background), make sure to replace the filenames with your actual image filenames. The backgrounds will be loaded from the root folder. So in this case our directory structure would look like this if our backgrounds were in the res folder:

"res/yourbackground.png"
"res/anotherbackground.png"

You should now see your background when selecting your game mode. Now if you haven't noticed already, when actually playing the game mode, everything is a bit strange. Lets fix this by initializing our speed settings and various other options.

Game Mode Settings

--[[ This Function gets called once when the game is loaded --]]
function start()
  -- Set the name of our game mode to "Tutorial" with a red frame
  initGameMode("Tutorial", 255, 0, 0)
  -- Set the number of backgrounds to two
  initBackgrounds(2)

  -- Load our two backgrounds
  initBgIdx(0, "yourbackground.png")
  initBgIdx(1, "anotherbackground.png")

  -- Set our background to the first background
  setBackground(0)

  -- game mode settings
  setDAS(16)             -- Delayed Auto Shift
  setARR(1)              -- Auto Repeate Rate
  setARE(30)             -- Appearance Delay
  setLineARE(0)          -- Line Appearance Delay
  setClearSpeed(41)      -- Line Clear Speed
  setLockDelay(40)       -- Lock delay
  setGravity(4)          -- Gravity (max is 5120, which is 20G)
  setPreview(3)          -- Number of next pieces displayed
  setBagRetry(6)         -- Number of times that will be attempted to generate a piece not in the bag
  setGradeType(0)        -- Choose between two predefined grade types (0, 1) or create your own (2)
  setGrade(0)            -- Grade (0-17) 0 = 9, 17 = Grand Master
  setSevenBag(true)      -- Use 7 bag piece generation?
  setHold(true)          -- Enable hold?
  setSonicDrop(true)     -- Enable sonic/hard drop?
  setExtraKicks(true)    -- Enable extra classic kicks? (extra I and T kicks)
  set3D(true)            -- Enable psuedo 3D effect?
  setDrawNextBg(true)    -- Enable background behind piece preview?
  setBig(false)          -- Enable big mode?
  setInvis(false)        -- Enable invisible pieces?
  setDisplayGrade(false) -- Display internal grade (based on gradeType)?
  setGhost(true)         -- Enable piece ghost?
  setCreditRoll(false)   -- Show credit roll?
  setMaxLevel(900)       -- Maximum select level
  setSectionLevel(100)   -- Section Level
  setLevel(0)            -- Current Level
end

Here are some good starting settings for our game mode. If you want to learn more about these functions and their parameters, view the documentation. This marks the end of our start function, now is where the real fun begins. Lets add some stuff to our advanceLevel() function.

Game Mode Logic

--[[ This function gets called every time a piece locks to the PlayField --]]
function advanceLevel(amount, lineCount)

  setLevel(getLevel() + amount + lineCount)

  if (getLevel() >= 100) then
    setBackground(1)
    setGravity(5120)
  else
    setBackground(0)
    setGravity(4)
  end
end

Now we added some code that will increase our level, and also increase the gravity to max speed when we reach level 100. Obviously, this is not a very well designed game mode. It is up to you to add a speed progression system, grading, system, scoring system, and whatever else you want!