On the MiniScript Discord this week, one of our users (Luckythespacecat) shared an animation he made for his Steam game Wishlist Boreal. It looks like an open book, with the page turning as if advancing through the book, including a nice paper-ish curl as it goes. That led to another user (@dslower) pointing out this Instagram reel in which somebody makes a texture-mapped page flip animation, also with a nice curvy page.
And then he had the audacity to opine that you couldn't do such a thing in Mini Micro.
Challenge Accepted
In fact we can do such things in Mini Micro! The trick is just to break the curving surface up into flat quadrilaterals, and then render each quad as a Sprite.
Normally in these tutorials I walk through developing the code step by step — build a little, test a little. But this program is short enough that I think I'll try the opposite: present the full code, and then just explain how it works.
So, for maximum fun, fire up your copy of Mini Micro, edit a new program, and paste in the following code.
import "mathUtil"
clear
display(2).mode = displayMode.pixel
gfx = display(2)
gfx.clear color.clear
debug = false
pageTextures = [
file.loadImage("page1.png"),
file.loadImage("page2.png")]
pageWidth = 250
pageHeight = 400
xDivs = [0, 0.025, 0.05, 0.1, 0.2, 0.3, 0.4, 0.5, 0.7, 1]
pageSprites = []
lastU = 0
for i in range(1, xDivs.len - 1)
sp = new Sprite
sp.image = pageTextures[0]
sp.setUVs [[lastU, 0], [xDivs[i], 0], [xDivs[i],1], [lastU, 1]]
pageSprites.push sp
lastU = xDivs[i]
end for
display(4).sprites += pageSprites
getPolarPoint = function(pagePt, t, forward=true)
radius = pageWidth * pagePt * (cos(t*2*pi)*0.2 + 0.9)
if not forward then
t2 = t^pagePt
angle = mathUtil.lerp(0, 180, (t+t2)/2)
else
t = 1 - t
t2 = t^pagePt
angle = mathUtil.lerp(180, 0, (t+t2)/2)
end if
return [radius, angle]
end function
polarToXY = function(polarPt, baseX=480, baseY=320)
radius = polarPt[0]
ang = polarPt[1] * pi/180
x = baseX + cos(ang) * radius
y = baseY + sin(ang) * radius
// apply a minimum representing the thickness of the pages
// underneath, leaving a "dip" at the binding in the center
thickness = 16
q = abs(x - baseX) / pageWidth * 10
if q < 1 then
thickness *= sqrt(1 - (1-q)^2) // (section of a circle)
end if
y = mathUtil.max(y, baseY + thickness)
return [x,y]
end function
framePoly = function(corners)
for i in range(-1, corners.len-2)
p0 = corners[i]
p1 = corners[i+1]
gfx.line p0[0], p0[1], p1[0], p1[1], "#FF00FF", 2
end for
end function
render = function(t, forward=true)
if debug then gfx.clear color.clear
topPts = []
botPts = []
for pagePt in xDivs
p = getPolarPoint(pagePt, t, forward)
topPts.push polarToXY(p, 480, 50 + pageHeight)
botPts.push polarToXY(p, 480, 50)
end for
for i in pageSprites.indexes
pageSprites[i].setCorners [
[botPts[i][0], botPts[i][1]],
[botPts[i+1][0], botPts[i+1][1]],
[topPts[i+1][0], topPts[i+1][1]],
[topPts[i][0], topPts[i][1]] ]
if topPts[i+1][0] >= topPts[i][0] then
// front surface
pageSprites[i].image = pageTextures[0]
u0 = xDivs[i]
u1 = xDivs[i+1]
else
// back surface
pageSprites[i].image = pageTextures[1]
u0 = 1 - xDivs[i]
u1 = 1 - xDivs[i+1]
end if
sp.setUVs [[u0, 0], [u1, 0], [u1, 1], [u0, 1]]
if debug then framePoly pageSprites[i].corners
end for
end function
pageState = 0 // 0: page on the right; 1: flipped to the left
render pageState
turnPage = function(toState=1)
delta = sign(toState - 0.5) * 0.02
while pageState != toState and not key.available
yield
outer.pageState += delta
if pageState < 0 or pageState > 1 then
outer.pageState = mathUtil.clamp(pageState)
end if
render pageState, toState
end while
end function
// Main loop
while true
k = key.get
if k == char(27) or k == "q" then break // Esc or Q to quit
if k == "d" then
debug = not debug
gfx.clear color.clear
render pageState
end if
if k == char(17) then turnPage 1
if k == char(18) then turnPage 0
if k == char(10) or k == " " then turnPage not pageState
end while
You'll also need two page images: one for the front, and one for the back of the turning page. You can use whatever you like, but to match my demo, download these and save them as page1.png and page2.png:
Now run the program, and press the left/right arrow keys to flip the page. It should look like this:
Neat, right?
Carving up the Page
The secret sauce here is to divide the page into vertical strips, each of which is flat. In the demo, if you press the "d" (for "debug") key, it will actually draw the outlines of those quads, so you can see them.
You can divide the page however you like, but in my animation, I found that the curvature is much greater near the book binding (the left side of the original page) than on the outer (right) side of the page. So I made the divisions smaller on the left, and larger on the right. If we use 0 to refer to the left side of the page image, and 1 to refer to the right, then a sensible set of key points (dividing lines between the quads) might be:
xDivs = [0, 0.025, 0.05, 0.1, 0.2, 0.3, 0.4, 0.5, 0.7, 1]
...which in fact you will find as line 15 in the code.
To render any textured quad in Mini Micro, just make a Sprite, set its image property to the texture image, and then use setCorners and setUVs to position the quad on the screen, and select what part of the texture it displays. setCorners takes a list of four [x,y] pairs, in screen coordinates. setUVs takes a list of four [u,v] pairs, where u goes from 0-1 horizontally across the image (exactly like our xDivs values above), and v goes from 0-1 up the image vertically.
If you need a review on setCorners and setUVs, play around with the spriteStretch demo found in /sys/demo/.
In our page-flip demo, you'll find a loop at lines 17-26 which prepares our sprites based on the xDivs we defined above.
pageSprites = []
lastU = 0
for i in range(1, xDivs.len - 1)
sp = new Sprite
sp.image = pageTextures[0]
sp.setUVs [[lastU, 0], [xDivs[i], 0], [xDivs[i],1], [lastU, 1]]
pageSprites.push sp
lastU = xDivs[i]
end for
display(4).sprites += pageSprites
Later (starting at line 65), we have a render function that updates those same sprites to reflect the current state of the animation. It begins by building a set of x,y coordinates for the points along the top and bottom of the page:
topPts = []
botPts = []
for pagePt in xDivs
p = getPolarPoint(pagePt, t, forward)
topPts.push polarToXY(p, 480, 50 + pageHeight)
botPts.push polarToXY(p, 480, 50)
end for
The heavy lifting here is being done by getPolarPoint and polarToXY, which we'll get to in a moment. For now, just understand that we're taking our xDivs points along the page, and converting them into screen coordinates for the top (topPts) and bottom (botPts) of the page. Then we just use those to update the corners of each corresponding sprite.
for i in pageSprites.indexes
pageSprites[i].setCorners [
[botPts[i][0], botPts[i][1]],
[botPts[i+1][0], botPts[i+1][1]],
[topPts[i+1][0], topPts[i+1][1]],
[topPts[i][0], topPts[i][1]] ]
end for
If we wanted to show the same content (but reversed) on the back of the page, this would be all we need. But really we want to show a different image on the back of the page, and because the sprites are flipped horizontally by that point, we need to invert the U coordinates as well. So we need to insert some extra code into the above for loop to update the image and UV coordinates:
if topPts[i+1][0] >= topPts[i][0] then
// front surface
pageSprites[i].image = pageTextures[0]
u0 = xDivs[i]
u1 = xDivs[i+1]
else
// back surface
pageSprites[i].image = pageTextures[1]
u0 = 1 - xDivs[i]
u1 = 1 - xDivs[i+1]
end if
sp.setUVs [[u0, 0], [u1, 0], [u1, 1], [u0, 1]]
Now each section not only draws in the right position, but also shows the correct part of the right texture, depending on whether it's flipped.
Computing the Page Shape
For me, drawing the texture-mapped quads was the easy part. The hard part was actually animating the shape of the page throughout the flip.
You could just use keyframe animation: that is, make a tool (similar to that spriteStretch demo) that lets you drag the top and bottom points around by hand, and record the correct position for key frames throughout the flip. Alternatively, you could use some external animation tool that writes to a file you can read in your Mini Micro program. Then just play those positions back, interpolating as needed for in-between frames.
But I didn't have the patience (nor, most likely, the art skills) for all that, so I went for a more mathematical approach. Since the page is essentially rotating around its attachment point (the left side of the unflipped page), I found it easier to think about it in polar (radius and angle) rather than Cartesian (x and y) coordinates. Some trial and error led me to this function.
getPolarPoint = function(pagePt, t, forward=true)
radius = pageWidth * pagePt * (cos(t*2*pi)*0.2 + 0.9)
if not forward then
t2 = t^pagePt
angle = mathUtil.lerp(0, 180, (t+t2)/2)
else
t = 1 - t
t2 = t^pagePt
angle = mathUtil.lerp(180, 0, (t+t2)/2)
end if
return [radius, angle]
end function
getPolarPoint takes:
- a page point, i.e., one of those
xDivspoints along the page from 0 (left) to (1) right -
t, how far we are in the flip animation from 0 (starting position) to 1 (complete) -
forward, which istruewhen flipping forward (right to left) andfalsewhen flipping back the other way.
The first version of this function had just radius = pageWidth * pagePt; angle = mathUtil.lerp(0, 180, t) -- that is, a constant radius, and an angle that interpolates smoothly between 0 and 180 degrees. This creates a stiff page that flips without bending. The rest of the final code was just to fancy it up: make the radius a little smaller towards the center of the animation, and add a bit of curl by changing the angle based on how far along the page we are (and how far we are in the animation).
But to actually use this, we have to convert from polar coordinates back to XY coordinates. The basic function for that would be:
polarToXY = function(polarPt, baseX=480, baseY=320)
radius = polarPt[0]
ang = polarPt[1] * pi/180
x = baseX + cos(ang) * radius
y = baseY + sin(ang) * radius
return [x,y]
end function
But while I was at it, I decided to have this conversion function also apply some "thickness" to the book, by calculating a minimum Y that varies with our distance along the page. This was to make the endpoints of the animation include a bit of a curl down where the page connects to the rest of the book, so it looks like an actual book with a binding, rather than a thin magazine or something.
The code for this (inserted into the function above) is:
// apply a minimum representing the thickness of the pages
// underneath, leaving a "dip" at the binding in the center
thickness = 16
q = abs(x - baseX) / pageWidth * 10
if q < 1 then
thickness *= sqrt(1 - (1-q)^2) // (section of a circle)
end if
y = mathUtil.max(y, baseY + thickness)
Incorporating Into Your Game
That's all our demo does. To incorporate this into a full game, you would need to draw the "rest" of the book (the open cover and pages underneath the turning page, and ensure that your page sprites are topmost.
Also, you'll probably have more than just one (front and back page). You might have lots of pages in your book. I would implement that with just three sets of page sprites:
- one that shows the resting right-hand page
- one for the resting left-hand page
- one for the actively turning page
At rest, you don't actually need the third one. But as soon as it's time to turn the page, you would add it to the view. If advancing through the book, the right-hand page is going to flip left. So you would set your third page with the content on the right, plus the subsequent page as its back; and update the resting right-hand page to show the page after that. Then animate. At the end of the animation, update the left-hand page to show the same thing as the animation page, and hide the animation page. If going backwards, you'd do something similar, but animating from left to right.
I toyed with the idea of making this into its own little library on GitHub that manages multiple pages, provides different ways of specifying the page animation, etc. But maybe it's not worth it; the core ideas are in this demo, and you can take it from here. Let me know what you think in the comments below, or join us on Discord to discuss more. I can't wait to see what you do with it!