mode7 version 0.3.0 Get Latest Release
mode7.scm (https://github.com/ericoporto/mode7/releases/download/0.3.0/mode7.scm) | GitHub Repo (https://github.com/ericoporto/mode7) | Download project .zip (https://github.com/ericoporto/mode7/archive/0.3.0.zip)
AGS Script Module for Mode7 like graphics.
See demo in here! (https://ericoporto.github.io/mode7/) (Use Firefox, Safari or Chrome 100+, WASD to move)
(https://user-images.githubusercontent.com/2244442/160260167-0f6ab7a0-fd55-472a-839f-5332f3970476.gif)
This module allows you to project a sprite on the screen with the visual aspect people are familiar from the mode7 graphics of SNES games. Use the Mode7 struct for that!
If you want to do more, and also want to have other elements in it, similar to Mario Kart, you can leverage Mode7World and Mode7Object functionalities.
This code is based on original code that was written by
Khris and presented in this ags forum thread (https://www.adventuregamestudio.co.uk/forums/index.php?topic=45834.msg636452606#msg636452606). I asked Khris for the original code, which was very Kart oriented, I refactored to what I thought was more generic and made this module in the hopes people could pick around the code and make games out of it!
A note, the original code was a bit more performant, I pulled out some specific optimizations to make the code more flexible.
Script APISpoiler
Mode7
Mode7.SetCamera
void Mode7.SetCamera(float x, float y, float z, float xa, float ya, float focal_length)
Sets the camera position, angle and focal length.
Mode7.SetViewscreen
void Mode7.SetViewscreen(int width, int height, optional int x, optional int y)
Sets the screen area it will draw in.
Mode7.SetGroundSprite
void Mode7.SetGroundSprite(int ground_graphic)
Sets the ground sprite, this is the mode7 rendered sprite.
Mode7.SetHorizonSprite
void Mode7.SetHorizonSprite(int horizon_graphic, eHorizonType = eHorizonDynamic)
Sets a sprite that will roll around in the horizon, you can also make it static.
Mode7.SetBgColor
void Mode7.SetBgColor(int bg_color)
Sets the color of the background where the ground sprite doesn't reach.
Mode7.SetSkyColor
void Mode7.SetSkyColor(int sky_color)
Sets the color of the sky.
Mode7.TargetCamera
void Mode7.TargetCamera(float target_x, float target_y, float target_z, float teta_angle, eCameraTargetType camType = eCameraTarget_FollowBehind, bool is_lazy = true)
Target the camera to something.
Mode7.Draw
void Mode7.Draw()
Draws the ground sprite and horizon rendered in the Screen sprite.
Mode7.ResetGround
void Mode7.ResetGround()
Clears the screen sprite.
Mode7.CameraAngleX
float Mode7.CameraAngleX
The camera angle that is normal to the ground plane (e.g.: up and down).
Mode7.CameraAngleY
float Mode7.CameraAngleY
The camera angle that is on the ground plane (e.g.: left and right).
Mode7.Screen
DynamicSprite* Mode7.Screen
The Dynamic Sprite that represents the screen where the Mode7 ground is draw to.
Mode7World
This is an extension of Mode7 and gives you tools to present billboard sprites, positioned in the world coordinates, using the concept of Mode7Objects. You don't have to use it to do the drawing, but it should help you if you want to!
Mode7World.AddObject
Mode7Object* Mode7World.AddObject(int x, int z, float factor, int graphic)
Adds an object, and sets it's x and z position. The y (vertical position) is always zero. You also must pass a scale factor and it's graphics.
Mode7World.AddExternalObject
void Mode7World.AddExternalObject(int x, int z, float factor, int graphic)
Adds an external object that is not managed by the Mode7World. It will still be updated and draw, but removing it from the world will probably not garbage collect it.
Mode7World.RemoveObject
void Mode7World.RemoveObject(int object_i = -1)
Remove a specific object from the world by it's index. If you don't pass a value, it will remove the last valid object added.
Mode7World.RemoveAllsObjects
void Mode7World.RemoveAllsObjects()
Removes all objects from the Mode7 World.
Mode7World.GetAngleObjectAndCamera
int Mode7World.GetAngleObjectAndCamera(Mode7Object* m7obj)
Returns the angle in degrees between the camera and whatever angle is set to a specific object, pointed by their index. Useful when you want to change the graphic of an object based on their relative angle.
Mode7World.UpdateObjects
void Mode7World.UpdateObjects(optional bool do_sort)
Update the screen transform of all objects world positions to their screen positions. You must call it before drawing any objects! You can optionally skip any sorting if you plan rendering using overlays later, since they have zorder property which will be used later by the graphics driver.
Mode7World.DrawObjects
void Mode7World.DrawObjects()
Draws only the objects in the screen sprite. You can use when you need to draw additional things between the ground and the objects. Or when you don't need the ground at all.
Mode7World.DrawObjectsOverlay
void Mode7World.DrawObjectsOverlay()
Draws objects as overlays, without rasterizing at the screen sprite.
Mode7World.DrawWorld
void Mode7World.DrawWorld()
Draws the ground sprite and the objects over it, in the screen sprite.
Mode7World.DrawWorld2D
DynamicSprite* Mode7World.DrawWorld2D()
Gets a dynamic sprite with the world draw in top down view, useful for debugging.
Mode7World.Objects
writeprotected Mode7Object* Mode7World.Objects[i]
Let's you access a specific object in the mode7 world by it's index. Make sure to access a valid position.
Mode7World.ObjectCount
writeprotected int Mode7World.ObjectCount
Gets how many objects are currently in the mode7 world.
Mode7World.ObjectScreenVisibleCount
writeprotected int Mode7World.ObjectScreenVisibleCount
Gets how many objects are actually visible in the screen.
You can iterate through all the screen objects as follows:
for(int i=0; i < m7w.ObjectScreenVisibleCount; i++)
{
// will make sure to access in order from far to closer
int index = m7w.ObjectScreenVisibleID[m7w.ObjectScreenVisibleOrder[i]];
Obj* m7object = m7w.Objects[index];
// do as you you must with you m7object ...
}
Mode7Object
A Mode7Object, you should create objects by using Mode7World.AddObject. After world coordinates are set, you can use Mode7World.UpdateObjects to transform it's coordinates and get updated values in it's Screen prefixed properties.
Mode7Object.SetPosition
void Mode7Object.SetPosition(float x, float y, float z)
A helper function to setting the Object world position in a single line.
Mode7Object.Draw
void Mode7Object.Draw(DrawingSurface* ds)
Draw the object in a DrawingSurface as it would look in a screen.
Mode7Object.X
float Mode7Object.X
Object World X Position on the plane.
Mode7Object.Y
float Mode7Object.Y
Object World Y Position, perpendicular to plane.
Mode7Object.Z
float Mode7Object.Z
Object World Z Position, orthogonal to X position.
Mode7Object.Factor
float Mode7Object.Factor
Object Scaling factor to it's graphics.
Mode7Object.Angle
float Mode7Object.Angle
Object angle, parallel to plane, not used for rendering.
Mode7Object.Graphic
int Mode7Object.Graphic
Object sprite slot, it's width and height is used to calculate the screen coordinates.
Mode7Object.Visible
bool Mode7Object.Visible
Object visibility.
Mode7Object.ScreenX
int Mode7Object.ScreenX
On-Screen Object X position when drawing, if visible. It's regular top, left coordinates, similar to GUI, assumes a Graphic is set.
Mode7Object.ScreenY
int Mode7Object.ScreenY
On-Screen Object Y position when drawing, if visible. It's regular top, left coordinates, similar to GUI, assumes a Graphic is set.
Mode7Object.ScreenWidth
int Mode7Object.ScreenWidth
On-Screen Object Width when drawing, if visible. It's adjusted by the sprite used in Graphic, projection and scaling factor.
Mode7Object.ScreenHeight
int Mode7Object.ScreenHeight
On-Screen Object Height when drawing, if visible. It's adjusted by the sprite used in Graphic, projection and scaling factor.
Mode7Object.ScreenVisible
bool Mode7Object.ScreenVisible
True if object should be drawn on screen. Gets set to false if object is culled when projecting.
Mode7Object.ScreenZOrder
int Mode7Object.ScreenZOrder
ZOrder of the object when drawing on screen, smaller numbers are below, bigger numbers are on top.
This is just a quick initial release, I plan to update this soon with a better demo and polish the API and other stuff!
- v0.1.0 - initial release.
- v0.2.0 - added ResetGround, CameraAngleX, CameraAngleY to Mode7, added Visible to Mode7Object, added AddExternalObject and DrawWorld2D to Mode7World, change GetAngleObjectAndCamera api.
- v0.3.0 - added support for using Overlays for rendering mode7 objects using Mode7World.DrawObjectsOverlay, and also to skip sorting for overlay based drawing.
3D Overrated
2D Outdated
Long have we waited
MODE 7 ACTIVATED!!
This is awesome, ofc, that would have helped before i botch-coded my own version!
Awesome! I just realized that speed sailing a viking ship around some tropical islands is the perfect start to my day! ;-D
@Dualnames â¤ï¸â¤ï¸â¤ï¸
@heltenjon I have a thing for the sea 8-)
Ooh, this looks great! Makes you want to create a racing game :-D
I need to try it out!
Quote from: eri0o on Tue 29/03/2022 15:17:50
@heltenjon I have a thing for the sea 8-)
I know. You rented a boat! (https://www.adventuregamestudio.co.uk/site/games/game/2530-i-rented-a-boat/) :-D
Wacky Wheels and Mario Kart were favourite racers as a kid 8-)
So cool! Great job as always!
This is great!This is just what i've been looking for.
I love it! ;-D
This is AWESOME!
I've even got an idea of what I could use it for... :-D
Incredible! Wizardry! :)
Hey, thanks everyone for the reception! Again, this would not be possible without Khris original code that made pretty much all the hard math!
I am making a new game to try to stress test this, so I will added some more features to this in a near future. For now, made a 0.2.0 release with some minor additions and fixes.
On a side note, theoretically speaking AGS is capable of rendering textures in full 3D, that is, for example, it could render a sprite rotated at a given angle along non-z axis, to achieve similar effect as the water in this demo game (or race track in AGS Kart demo game).
The biggest issue is the lack of "3d pipeline" as some called it, or in human words - there's no script commands and internal functions that would let configure this at the moment.
(https://i.imgur.com/DoOv5F9.gif)video here (https://imgur.com/nKav3G9)
Quote from: Crimson Wizard on Sun 03/04/2022 15:45:24
On a side note, theoretically speaking AGS is capable of rendering textures in full 3D, that is, for example, it could render a sprite rotated at a given angle along non-z axis, to achieve similar effect as the water in this demo game (or race track in AGS Kart demo game).
Having a hardware accelerated way would make it possible to handle a ton more things in the drawing space!
Once ags itself has the accelerated drawing capabilities, I hope the future module additions though are still useful for the world part - I plan to at some point make a Mode7BigWorld or similar for the object streaming pictured above. (for now though, I don't know the proper API to this so I just started to randomly experiment with the idea yesterday, code here: https://github.com/ericoporto/roading/blob/main/roading/zone_manager.ash)
Spoiler
More stuff on the topic idea... Here's a lod like approach, where far away things get baked in the ground to cheap the drawing process
(https://user-images.githubusercontent.com/2244442/161439322-66c5f427-637e-40de-9c93-f0f0a7614e20.gif)video here (https://i.imgur.com/xGpPrAk.mp4)
(maximum limits so far: https://ericoporto.github.io/agsjs/trees/ )
I updated the mode7 plugin module to version 0.3.0.
This introduces DrawObjectOverlays, which will allow rendering using Overlays instead of drawing a sprite. This can be significantly faster, and will allow a lot more objects to be on screen simultaneously.
The web demo has been upgraded to use this method.
I am working on a next version that will introduce big worlds with zoning, shown in the previous screencaps. I do plan a refactor at some point to simplify the API, but I am not sure yet how or when that will happen...
This is just... WOW.
I'm toying with a short-ish MAGS game at some stage, Sci-Fi focussed. To have a ship-flying section with this (starfields streaking by with planets as large pixelated objects) could work, perhaps! Keen to give this a go right now, but can't see it fitting into my current project!
Keep up the great work!
Quote from: eri0o on Sun 17/04/2022 22:20:15
I updated the mode7 plugin to version 0.3.0.
Plugin?
Quote from: eri0o on Sun 17/04/2022 22:20:15
rendering using Overlays instead of drawing a sprite. This can be significantly faster, and will allow a lot more objects to be on screen simultaneously.
Why is that? How are overlays quicker than how you were rendering it before?
Oh shoot, do not write things when you are sleepy people... I meant module.
So overlays are faster for two reasons
- You push your bitmap graphic to a texture, and instead of bliting it's pixels from that moment forward you just move the texture on screen, no need to keep reading those pixels every frame
- when drawing things on with sprite drawing, you need to do so in the order, you blitz the sprites from the back and then the ones next until the ones near are drawn, and to do so you need to order the sprites before you can draw then. The ordering is VERY SLOW in AGS Script, it has a great impact on drawing the pixels! When using overlays you can set the ZOrder property and let's the AGS graphics driver do the ordering, which is much faster.
So by "sprite drawing" you mean RawDrawing all the sprites to the background each frame?
Yeah, Dynamic Sprite DrawImage function.
But seriously, the ordering impacted more in frame rate when going for a low resolution. At low resolution, traversing the array for bubblesort took a ton of time. I attempted a quicksort too, but it did not improve at all (if you search the advanced technical forums I have done a quicksort in AGS script there at some point).
Ordering was very expensive to do on each frame, thus for dynamic sprite based software render in the module there's probably things to investigate in ordering algorithms.
If you feel like playing with the code at a later time, just fork it on GitHub and mess with it, it's possible you will find something interesting through experimenting, then please tell me back. :)
Overlays happened to be the most useful kind of object in todays AGS when you need a large number of moving and transformed (scaled etc) sprites on screen.
* overlays are designed unlimited (limited only by the program memory)
* they are rendered as a texture and thus accelerated by the graphics card (if you run with Direct3D / OpenGL render).
* it's a tiny structure without any superfluous properties that may screw logic up if not taken care of.
Before 3.6.0 room objects and characters could be more performant, as overlays did not support scaling for some reason, but since 3.6.0 beta Overlays may be scaled too
(https://www.adventuregamestudio.co.uk/forums/index.php?topic=59842.msg636645302#msg636645302)
PS. There's currently a serious issue remaining with overlays that they don't share a sprite reference, but make a bitmap copy; i believe this should be taken care of in the future.
Quote from: eri0o on Mon 18/04/2022 11:45:24
But seriously, the ordering impacted more in frame rate when going for a low resolution. At low resolution, traversing the array for bubblesort took a ton of time. I attempted a quicksort too, but it did not improve at all (if you search the advanced technical forums I have done a quicksort in AGS script there at some point).
Ordering was very expensive to do on each frame, thus for dynamic sprite based software render in the module there's probably things to investigate in ordering algorithms.
Ah, so when working with overlays you just set the Z-order to be the distance, and the driver takes care of the sorting. I was thinking of the Z-order as the sorting order, and figured you would still need to re-sort them whenever you moved.
I think you could probably optimize something similar for the draw sorting, where you build the sort order as you calculate the object distances (and possibly leverage the idea that most things will remain in the same order as in the last frame), but clearly that adds a lot of complexity.
This module + demo games really looks super cool. I'd never thought to see mode7 that fluent with just plain AGS script.
But there's more to it than just drawing on an overlay instead of a room's surface, right?
And is there a particular thread discussing the new possibilities with overlays? All I remember is that when I did my weather module back in 2008, overlays were rather limited.
Quote from: abstauber on Mon 18/04/2022 19:58:02
And is there a particular thread discussing the new possibilities with overlays?
There's not that much to mention, this is a relevant part of the change list (you may find it in the 3.6.0 release thread):
Quote
- Added Overlay.Width and Height properties, that let you freely scale existing Overlay.
- Added readonly Overlay.GraphicWidth and GraphicHeight properties that let read original overlay's graphic size (for textual overlays too).
- Added Overlay.Transparency property.
- Added Overlay.ZOrder property that lets you sort Overlays on screen among themselves and GUI.
EDIT: oh right, and also quite important
Quote- Removed Overlay limit.
So basically overlays at the moment are the only graphical object in game that a) is not limited b) may be created and deleted in script.
Hum, I need to write the manual entry, but the gist is:
Overlays are unlimited (it used to be possible to have at maximum 20 overlays)
You can move them on screen, set width and height, and transparency. You can also set their Z order.
Other than this you can now access directly the portrait and text overlays used by the engine sierra speech (and other speech modes I think).
(https://user-images.githubusercontent.com/2244442/162595346-1dba4a8f-fca8-4c93-8c3d-0d83ac8dd076.gif)
Here's an example game to play around:
keysAndCups.zip (https://github.com/adventuregamestudio/ags/files/8457948/keysAndCups.zip)
Edit: CW answered too, but yeah. That does already makes it useful to do things. Like, I can probably do a cutdown version of my imgi module to provide a scripted hardware accelerated GUI if I remove the scrolling component from that module.
Here's a demo I placed hidden above: https://ericoporto.github.io/agsjs/trees/
Has to be run in a desktop computer with a mouse, WASD walks, C switches in and out of the Ship, mouse movement looks around or set direction. As you click, the game will enter fullscreen, and grab the mouse and set the mouse to infinity mode - this is still a bit hackish in the Web port, so as you exit the fullscreen the mouse will be released and not work in it anymore...
Ah okay, thanks for the clarification.
I might have some more question, but I'll start a separate thread.
Back to topic ;)
Hey mods, I hope it's OK to ask questions about a module that hasn't been commented on in over a year.
I'm trying to experiment with the module and having difficulty.
Right now I'm just trying to set a ground sprite and get it to be visible when I run the game. Nothing else yet.
I started with the blank game template, one empty room, and a player character with no sprite, set to start in the empty room. Then I imported a single ground sprite (slot 1).
I wrote this code, based on my best understanding of the script API detailed in the original post above:
// room script file
Mode7 ThePlace;
function room_Load()
{
ThePlace.SetViewscreen(640, 180, 0, 0); //should cover half of screen. I'm assuming 0,0 places top left corner of drawing in top left corner of game viewport screen. Tried it at 320, 180 (center of screen) as well, with no difference in effect.
ThePlace.SetGroundSprite(1); //some green ground
ThePlace.SetCamera(0.0, 0.0, 0.0, 0.0, 0.0, 0.0); //This will turn out to be a problem, but changing it all to 1.0 doesn't fix everything.
ThePlace.Draw();
}
First I get an error saying sprite 19 doesn't exist. I wonder where this is called from and find it in line 111 of the Mode7 script. Not sure what that's about. I import 18 more sprites, all unique, then run again.
This time I get an error saying line 222 is dividing by zero. I look there and see it seems related to the camera. Change all camera values to one, like so:
Mode7.SetCamera(1.0, 1.0, 1.0, 1.0, 1.0, 1.0);
This time the game runs but I still just get a black screen with nothing drawn. Did I miss a command?
@RootBound The signature of the SetCamera method is
void Mode7.SetCamera(float x, float y, float z, float xa, float ya, float focal_length)x,y,z is the position, so y should be greater than 0 or the camera is inside the plane.
xa and ya are the camera angles, i.e. xa determines the direction the camera is facing, ya is the up/down angle afaik.
xa can be anything from 0 to 2 * Pi, but values outside that range should wrap around. ya is supposed to be something like -0.1 for instance, i.e. the camera is slightly looking down.
The last value is the focal length, essentially a zoom factor. Try values like 35.0.
Hi
@Khris thanks so much for the response. I tinkered with the values (also tried changing the ground sprite in case that was causing the problem) and unfortunately I am still just getting a black screen.
Here's the entirety of the room code:
// room script file
Mode7 ThePlace;
function room_Load()
{
ThePlace.SetViewscreen(100, 100, 100, 100);
ThePlace.SetGroundSprite(17);
ThePlace.SetCamera(10.0, 10.0, 10.0, 1.0, -0.1, 35.0);
ThePlace.Draw();
}
Any other errors you see? I appreciate it.
The .Draw() call goes into room_RepExec; other than that I don't see an error.
The SetViewScreen command expects x, y, width and height, so setting all to 100 should work.
Thanks
@Khris. I put the Draw() in room_RepExec, and I imported a very simple background image to the room just to make sure the room is actually loading. It does fade in, but no mode7 objects are drawn.
@eri0o do you have any thoughts?
Maybe the camera position and angle causes the mode7 ground to be off-screen?
Try
ThePlace.SetCamera(0.0, 10.0, 0.0, 0, -0.1, 100.0);
I think there are some debug keys you can use to move the camera around. I, K, O, L all do something with the camera at least in the demo. Arrow keys, too.
@Khris No change unfortunately.
@newwaveburritos Didn't get a response from the debug keys either. I saw you're making your own game with mode7. What did you use as your starting base? Did you use a template and then add the module?
Those keys only work if they are handled accordingly, which isn't the case with just the module.
Not sure how to debug this tbh; can you maybe start with the demo game instead?
I definitely worked backwards from the demo rather than forward from the module.
Thanks, both of you. The issue I was having with working backwards from the demo is that there is so much there that I don't know what is needed.
All I want is to create a mode7 ground object(?) that I can move across in one direction at several different (controllable) speeds, and to be able to track the mode7 camera coordinates so that I can teleport the camera back to the start when the camera reaches a certain point, and then change the ground texture. I don't need the boat or the sky or the 360 degree movement or even keyboard control.
This feels like it should be doable with the module but I don't know where to start with the whole demo in place.
I found the missing piece: the module only draws to its DynamicSprite, and you have to draw that to the room:
function room_RepExec()
{
ThePlace.Draw();
DrawingSurface* ds = Room.GetDrawingSurfaceForBackground();
ds.DrawImage(0, 0, ThePlace.Screen.Graphic);
ds.Release();
}
Quote from: Khris on Thu 07/09/2023 13:02:19I found the missing piece: the module only draws to its DynamicSprite, and you have to draw that to the room:
IT WORKS!!! ;-D ;-D ;-D Now I can actually start experimenting!
Amazing. Thanks a million.
EDIT: turns out this has nothing to do with the background, actually. This is the "sprite 19" issue from my original post. Sprite 19 was the same as the background image. Easy workaround is to make sprite 19 transparent. Doesn't solve the underlying issue, but it works.
Something extremely strange is happening. It appears that a copy of the room background image (in this case two color blocks) is being drawn on top of the mode7 ground texture. Could this an issue with GetDrawingSurfaceForBackground, or do you think the mode7 module is not drawing the texture correctly?
(https://i.imgur.com/KusUj67.png)
Experiment is making progress! Thanks again to
@Khris for all your help and to
@eri0o for the module. This is great fun.
Quote from: Khris on Thu 07/09/2023 13:02:19I found the missing piece: the module only draws to its DynamicSprite, and you have to draw that to the room:
BTW, you may assign the module's graphic to a room object or overlay to skip a second bitmap redraw and make things slightly faster. You may also do that once the dynamic sprite is created, probably at room load (?).
function room_Load()
{
// other set up
oObject1.Graphic = ThePlace.Screen.Graphic;
}
When the dynamic sprite is updated, the object's look will also get updated automatically.
Ha ha dang that looks great. My Quarantine-clone is kind of a pile by comparison.
I also encountered the Sprite 19 issue; the module is based on my old AGSKart code, and I simply hardcoded a bunch of stuff, including sprite slot 19 which ended up in Mode7::_DrawGroundSprites.
The workaround is to assign a random sprite to slot 19.
The two color block is probably due to the hard coded animated question mark; whatever you choose as sprite 19 ends up drawn to the ground on top of the main texture.
Oh yeah I did notice that question mark block as I was driving around doing the testing lol. I was just like "eh I'll figure that out later..."