Libs3D Library Shapes: Difference between revisions

From GiderosMobile
No edit summary
 
(16 intermediate revisions by the same user not shown)
Line 1: Line 1:
__TOC__
__TOC__
'''<big>Please note: there is [[Libs3D Library ShapesV2|a Shapes Library V2]]. We only keep this one for backward compatibility 🤷‍♂️</big>'''


== I am ready ==
== I am ready ==
Line 6: Line 9:
Here is the plan:
Here is the plan:
* start with a camera
* start with a camera
* a world to populate (scene)
** a world to populate (scene)
* add some primitive shapes (plane, cube, ...)
* some common 3D shapes (plane, cube, ...)
* load some .obj models
* light and shadows
* and some animations (bones)
* playground
 
Copy the following two '''Library''' folders in your project '''''assets''''' folder:
*'''3dbase'''
*'''luashader'''


== The Camera ==
== The Camera ==
Line 24: Line 31:
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
-- we position the view (camera) and set its target
-- we position the view (camera) and set its target
view:lookAt(0*8,0.3*8,0.8*8, 0*8,0*8,0*8) -- (eyex,eyey,eyez, targetx,targety,targetz[, upx,upy,upz])
view:lookAt(0.25*8,0.5*8,0.5*8, 0*8,0*8,0*8) -- (eyex,eyey,eyez, targetx,targety,targetz[, upx,upy,upz])
</syntaxhighlight>
 
In order to display the content of the Viewport (camera) to the screen, we add it to Gideros '''stage'''.
<syntaxhighlight lang="lua">
-- we add the view (camera) to Gideros stage
stage:addChild(view)
</syntaxhighlight>
</syntaxhighlight>


Line 37: Line 50:
We are going to use the Plane shape (helper file ''3DShapes.lua''), this will be our ground.
We are going to use the Plane shape (helper file ''3DShapes.lua''), this will be our ground.
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
-- a shape
-- our first shape, a plane for the ground
local ground = D3.Plane.new(1*8, 1*8) -- (width,depth)
local ground = D3.Plane.new(1*8, 1*8) -- (width,depth)
-- a color
-- a color
ground:mapColor(0x554333, 0.5) -- (color,[alpha=1])
ground:mapColor(0x9d7878) -- (color,[alpha=1])
</syntaxhighlight>
</syntaxhighlight>


Let's texture our plane, I picked this one: https://polyhaven.com/a/forrest_ground_01, '''Diffuse''', '''Normal (GL)''', '''1K''', '''JPG'''
Let's texture our plane, I picked this one: https://polyhaven.com/a/forrest_ground_01, '''Diffuse''', '''1K''', '''JPG'''


[[File:3d_plane_polyhaven_forrest_ground.png|480px]]
[[File:3d_plane_polyhaven_forrest_ground.png|480px]]


<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
-- a shape
-- a texture (diffuse)
local ground = D3.Plane.new(1*8, 1*8) -- (width,depth)
local tex = Texture.new("textures/forrest_ground_01_diff_1k.jpg", nil, { wrap=Texture.REPEAT, } )
-- a color
local texsx, texsy = 0.1*8, 0.1*8 -- texture scaling
--ground:mapColor(0x554333, 0.5) -- (color,[alpha=1])
ground:mapTexture(tex, texsx, texsy) -- (texture,sw,sh)
-- and its texture
local tex = Texture.new("models/textures/forrest_ground_01_diff_1k.jpg", nil, { wrap=Texture.REPEAT, } )
local normal = Texture.new("models/textures/forrest_ground_01_nor_gl_1k.jpg", nil, { wrap=Texture.REPEAT, } )
local texsx, texsy = 0.15*8, 0.15*8 -- texture scaling
ground:mapTexture(tex, texsx, texsy, normal)
</syntaxhighlight>
</syntaxhighlight>


Line 65: Line 73:
</syntaxhighlight>
</syntaxhighlight>


Finally, we add the ground to the scene and the view to Gideros '''stage'''.
And we add the ground to the world (scene).
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
-- we add the shape to the scene
-- we add the shape to the scene (world)
scene:addChild(ground)
scene:addChild(ground)
-- and the scene to stage
stage:addChild(view)
</syntaxhighlight>
</syntaxhighlight>


== More shapes ==
The Mesh3D class (''3DShapes.lua'') has other shapes you can use: '''D3.Cube''', '''D3.Sphere''', '''D3.Cylinder'''.
<syntaxhighlight lang="lua">
-- more shapes
local cube = D3.Cube.new(0.15*8, 0.17*8, 0.15*8)
cube:mapColor(0xb3ffb8) -- (color,[alpha=1])
texsx, texsy = 0.03*8, 0.03*8 -- texture scaling
cube:mapTexture(tex, texsx, texsy) -- (texture,sw,sh)
cube:setPosition(-0.2*8, 0.17*8, -0.05*8)
cube:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
scene:addChild(cube)


local sphere = D3.Sphere.new(2*8, 0.12*8) -- (steps,radius)
sphere:mapColor(0x55ff00) -- (color,[alpha=1])
texsx, texsy = 0.01*8, 0.01*8 -- texture scaling
sphere:mapTexture(tex, texsx, texsy)
sphere:setPosition(0.1*8, 0.12*8, 0.07*8)
sphere:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
scene:addChild(sphere)


local cylinder = D3.Cylinder.new(2*8, 0.1*8, 0.25*8) -- (steps,radius,height)
cylinder:mapColor(0xffaa00) -- (color,[alpha=1])
texsx, texsy = 0.05*8, 0.05*8 -- texture scaling
cylinder:mapTexture(tex, texsx, texsy)
cylinder:setPosition(0.3*8, 0.2, 0.15*8)
cylinder:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
scene:addChild(cylinder)
</syntaxhighlight>


== Lighting ==
The final touch is lighting (''3DLighting.lua'').


About lighting:
*''Lighting.setLight(x,y,z,a)'' sets the position of the light source (spotlight) and the amount of ambient light
*''Lighting.setLightTarget(x,y,z,d,f)'' sets the target of the light source. ''x,y,z'' is the position where the light is pointing at, ''d'' determines the projection distance when computing shadows (d gives the far plane, and the near plane is computed as d/16 internally). ''f'' is the FoV angle (actually the half angle), it determines the opening of your spotlight cone, and has a consequence on the shadow precision
*Only objects between d and d/16 in the light cone will cast shadows
*Select ''d'' wisely as it has an impact on shadow precision
*the lib uses a 1024x1024 shadow map


The light source position and ambient light.
<syntaxhighlight lang="lua">
-- light setup
local lsx, lsy, lsz = 0.4*8, 0.8*8, 0.4*8 -- light source position
Lighting.setLight(lsx,lsy,lsz, 0.35) -- (x,y,z, ambient)
</syntaxhighlight>


The light target has a position and a projection distance plus a field of view (fov) angle.
<syntaxhighlight lang="lua">
local ltx, lty, ltz = 0.0*8, 0.0*8, 0.0*8 -- light target position
local pd, fov = 3*8, 7*8
Lighting.setLightTarget(ltx,lty,ltz, pd,fov) -- (x,y,z, projection distance,fov)
</syntaxhighlight>


When we added the shapes to the world, we gave the shapes the ability to receive light and shadows: '''D3.Mesh.MODE_LIGHTING''', '''D3.Mesh.MODE_SHADOW'''. We need to compute the shadow map.
<syntaxhighlight lang="lua">
Lighting.computeShadows(scene)
</syntaxhighlight>


Please create a new Gideros project and copy the two following '''Library''' folders in the '''''assets''''' folder:
'''And voilà'''!
*'''3dbase'''
*'''luashader'''


Create a '''models''' folder, and in this folder an '''objs''' folder. I also add a '''textures''' folder. Your file structure should look something like this:
[[File:ss_3DShapes.png]]
*'''YourProjectName'''
**Plugins
**Files
***3dbase
***luashader
***models
****objs
****textures
***''main''.lua


You can run your project, you should have a blank screen.
== Playground ==
'''The full code'''
<syntaxhighlight lang="lua">
application:setBackgroundColor(0x454545)


== .obj Rulez ==
-- we set up a fullscreen 3D viewport (fov: consoles 60, pc 90)
When you work with 3D, you need to follow some "engine" rulez. In Gideros, for the '''.obj''' file format, those are:
local sw, sh = application:getContentWidth(), application:getContentHeight()
*'''currently Gideros supports ''.png'' and ''.jpg'' image formats'''
local view = D3.View.new(sw,sh, 90, 0.1,1*1024) -- (screen w,screen h, fov, near plane,far plane)
*'''currently Gideros supports ''Base Color'', ''Texture map'' and ''Normal Map'''''
*'''the textures shouldn't be embedded in the models. In Blender, use ''unpack resources''''':
[[File:Blender_unpack_resources.png|414px]]


*'''your Blender BSDF shaders should look something like''':
-- we position the view (camera) and set its target
[[File:Blender_shading_tab.png|558px]]
view:lookAt(0.25*8,0.5*8,0.5*8, 0*8,0*8,0*8) -- (eyex,eyey,eyez, targetx,targety,targetz[, upx,upy,upz])


*'''Gideros will import the position of the models, so make sure your models are at location 0, 0, 0'''
-- we add the view (camera) to Gideros stage
stage:addChild(view)


*'''I believe Gideros also imports the origin of the models, so place the origins accordingly'''
-- we will add 3D shapes and models to a scene
local scene = view:getScene()
--scene:setAutoSort(true)


'''I personally use this Blender add-on: https://extensions.blender.org/add-ons/act-game-asset-creation-toolset/'''
-- our first shape, a plane for the ground
 
local ground = D3.Plane.new(1*8, 1*8) -- (width,depth)
Please note, you can still have the ''Metallic'', ''Roughness'' and other textures attached in your Blender BSDF shaders, Gideros will just ignore them.
ground:mapColor(0x9d7878) -- (color,[alpha=1])
 
local tex = Texture.new("textures/forrest_ground_01_diff_1k.jpg", nil, { wrap=Texture.REPEAT, } )
== The assets: '''.obj''' ==
local texsx, texsy = 0.1*8, 0.1*8 -- texture scaling
I have chosen this cc0 asset pack: https://roadtovostok.itch.io/road-to-vostok-assets-vol1.
ground:mapTexture(tex, texsx, texsy) -- (texture,sw,sh)
 
-- we tell the shape to receive light and shadows
In 3D, the assets you download from the internet, often need some adjustement to follow your "engine" rulez 🤷‍♂️. I already made those adjustements and you can find the adjusted asset pack here: '''https://mokatunprod.itch.io/3dpixel-obj-packs'''.
ground:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
 
-- we add the shape to the scene
Please copy the '''roadtovostok''' asset pack (or your own models) in the ''objs'' folder:
scene:addChild(ground)
***models
****objs
*****roadtovostok


-- more shapes
local cube = D3.Cube.new(0.15*8, 0.17*8, 0.15*8)
cube:mapColor(0xb3ffb8) -- (color,[alpha=1])
texsx, texsy = 0.03*8, 0.03*8 -- texture scaling
cube:mapTexture(tex, texsx, texsy) -- (texture,sw,sh)
cube:setPosition(-0.2*8, 0.17*8, -0.05*8)
cube:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
scene:addChild(cube)


local sphere = D3.Sphere.new(2*8, 0.12*8) -- (steps,radius)
sphere:mapColor(0x55ff00) -- (color,[alpha=1])
texsx, texsy = 0.01*8, 0.01*8 -- texture scaling
sphere:mapTexture(tex, texsx, texsy)
sphere:setPosition(0.1*8, 0.12*8, 0.07*8)
sphere:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
scene:addChild(sphere)


local cylinder = D3.Cylinder.new(2*8, 0.1*8, 0.25*8) -- (steps,radius,height)
cylinder:mapColor(0xffaa00) -- (color,[alpha=1])
texsx, texsy = 0.05*8, 0.05*8 -- texture scaling
cylinder:mapTexture(tex, texsx, texsy)
cylinder:setPosition(0.3*8, 0.2, 0.15*8)
cylinder:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
scene:addChild(cylinder)


-- light setup
local lsx, lsy, lsz = 0.4*8, 0.8*8, 0.4*8 -- light source position
local ltx, lty, ltz = 0.0*8, 0.0*8, 0.0*8 -- light target position
Lighting.setLight(lsx,lsy,lsz, 0.35) -- (x,y,z, ambient)
local pd, fov = 3*8, 7*8 -- 5*8, 6*8
Lighting.setLightTarget(ltx,lty,ltz, pd,fov) -- (x,y,z, projection distance,fov)
Lighting.computeShadows(scene)


-- game loop
stage:addEventListener(Event.ENTER_FRAME, function(e)
cube:setRotationX(cube:getRotationX()+8*8*e.deltaTime)
sphere:setRotationY(sphere:getRotationY()+9*8*e.deltaTime)
cylinder:setRotationY(cylinder:getRotationY()+10*8*e.deltaTime)
Lighting.computeShadows(scene)
end)
</syntaxhighlight>


== I am out 2 ==
== I am out 2 ==
To do.
Please have a look at [[Libs3D Library ShapesV2|the Shapes Library V2]].


You are strongly encouraged to mess with the code.
You are strongly encouraged to mess with the code.

Latest revision as of 03:58, 1 August 2026


Please note: there is a Shapes Library V2. We only keep this one for backward compatibility 🤷‍♂️

I am ready

As we have seen, to make more advanced 3D, Gideros has a bunch of helper files packed in the Library folder.

Here is the plan:

  • start with a camera
    • a world to populate (scene)
  • some common 3D shapes (plane, cube, ...)
  • light and shadows
  • playground

Copy the following two Library folders in your project assets folder:

  • 3dbase
  • luashader

The Camera

The camera is a Viewport with a perspective projection Matrix (helper file 3DView.lua). Let's add one:

application:setBackgroundColor(0x454545)

-- we set up a fullscreen 3D viewport (fov: consoles 60, pc 90)
local sw, sh = application:getContentWidth(), application:getContentHeight()
local view = D3.View.new(sw,sh, 90, 0.1,1*1024) -- (screen w,screen h, fov, near plane,far plane)

You can position the view (camera) and set its target using the Viewport:lookAt function.

-- we position the view (camera) and set its target
view:lookAt(0.25*8,0.5*8,0.5*8, 0*8,0*8,0*8) -- (eyex,eyey,eyez, targetx,targety,targetz[, upx,upy,upz])

In order to display the content of the Viewport (camera) to the screen, we add it to Gideros stage.

-- we add the view (camera) to Gideros stage
stage:addChild(view)

The World (scene)

We will add all our 3D models to a scene. The scene is a simple Sprite and is part of the camera.

-- we will add 3D shapes and models to a scene
local scene = view:getScene()

Our first shape: a Plane

We are going to use the Plane shape (helper file 3DShapes.lua), this will be our ground.

-- our first shape, a plane for the ground
local ground = D3.Plane.new(1*8, 1*8) -- (width,depth)
-- a color
ground:mapColor(0x9d7878) -- (color,[alpha=1])

Let's texture our plane, I picked this one: https://polyhaven.com/a/forrest_ground_01, Diffuse, 1K, JPG

-- a texture (diffuse)
local tex = Texture.new("textures/forrest_ground_01_diff_1k.jpg", nil, { wrap=Texture.REPEAT, } )
local texsx, texsy = 0.1*8, 0.1*8 -- texture scaling
ground:mapTexture(tex, texsx, texsy) -- (texture,sw,sh)

We tell the shape to receive light and shadows.

-- we tell the shape to receive light and shadows
ground:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)

And we add the ground to the world (scene).

-- we add the shape to the scene (world)
scene:addChild(ground)

More shapes

The Mesh3D class (3DShapes.lua) has other shapes you can use: D3.Cube, D3.Sphere, D3.Cylinder.

-- more shapes
local cube = D3.Cube.new(0.15*8, 0.17*8, 0.15*8)
cube:mapColor(0xb3ffb8) -- (color,[alpha=1])
texsx, texsy = 0.03*8, 0.03*8 -- texture scaling
cube:mapTexture(tex, texsx, texsy) -- (texture,sw,sh)
cube:setPosition(-0.2*8, 0.17*8, -0.05*8)
cube:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
scene:addChild(cube)

local sphere = D3.Sphere.new(2*8, 0.12*8) -- (steps,radius)
sphere:mapColor(0x55ff00) -- (color,[alpha=1])
texsx, texsy = 0.01*8, 0.01*8 -- texture scaling
sphere:mapTexture(tex, texsx, texsy)
sphere:setPosition(0.1*8, 0.12*8, 0.07*8)
sphere:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
scene:addChild(sphere)

local cylinder = D3.Cylinder.new(2*8, 0.1*8, 0.25*8) -- (steps,radius,height)
cylinder:mapColor(0xffaa00) -- (color,[alpha=1])
texsx, texsy = 0.05*8, 0.05*8 -- texture scaling
cylinder:mapTexture(tex, texsx, texsy)
cylinder:setPosition(0.3*8, 0.2, 0.15*8)
cylinder:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
scene:addChild(cylinder)

Lighting

The final touch is lighting (3DLighting.lua).

About lighting:

  • Lighting.setLight(x,y,z,a) sets the position of the light source (spotlight) and the amount of ambient light
  • Lighting.setLightTarget(x,y,z,d,f) sets the target of the light source. x,y,z is the position where the light is pointing at, d determines the projection distance when computing shadows (d gives the far plane, and the near plane is computed as d/16 internally). f is the FoV angle (actually the half angle), it determines the opening of your spotlight cone, and has a consequence on the shadow precision
  • Only objects between d and d/16 in the light cone will cast shadows
  • Select d wisely as it has an impact on shadow precision
  • the lib uses a 1024x1024 shadow map

The light source position and ambient light.

-- light setup
local lsx, lsy, lsz = 0.4*8, 0.8*8, 0.4*8 -- light source position
Lighting.setLight(lsx,lsy,lsz, 0.35) -- (x,y,z, ambient)

The light target has a position and a projection distance plus a field of view (fov) angle.

local ltx, lty, ltz = 0.0*8, 0.0*8, 0.0*8 -- light target position
local pd, fov = 3*8, 7*8
Lighting.setLightTarget(ltx,lty,ltz, pd,fov) -- (x,y,z, projection distance,fov)

When we added the shapes to the world, we gave the shapes the ability to receive light and shadows: D3.Mesh.MODE_LIGHTING, D3.Mesh.MODE_SHADOW. We need to compute the shadow map.

Lighting.computeShadows(scene)

And voilà!

Playground

The full code

application:setBackgroundColor(0x454545)

-- we set up a fullscreen 3D viewport (fov: consoles 60, pc 90)
local sw, sh = application:getContentWidth(), application:getContentHeight()
local view = D3.View.new(sw,sh, 90, 0.1,1*1024) -- (screen w,screen h, fov, near plane,far plane)

-- we position the view (camera) and set its target
view:lookAt(0.25*8,0.5*8,0.5*8, 0*8,0*8,0*8) -- (eyex,eyey,eyez, targetx,targety,targetz[, upx,upy,upz])

-- we add the view (camera) to Gideros stage
stage:addChild(view)

-- we will add 3D shapes and models to a scene
local scene = view:getScene()
--scene:setAutoSort(true)

-- our first shape, a plane for the ground
local ground = D3.Plane.new(1*8, 1*8) -- (width,depth)
ground:mapColor(0x9d7878) -- (color,[alpha=1])
local tex = Texture.new("textures/forrest_ground_01_diff_1k.jpg", nil, { wrap=Texture.REPEAT, } )
local texsx, texsy = 0.1*8, 0.1*8 -- texture scaling
ground:mapTexture(tex, texsx, texsy) -- (texture,sw,sh)
-- we tell the shape to receive light and shadows
ground:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
-- we add the shape to the scene
scene:addChild(ground)

-- more shapes
local cube = D3.Cube.new(0.15*8, 0.17*8, 0.15*8)
cube:mapColor(0xb3ffb8) -- (color,[alpha=1])
texsx, texsy = 0.03*8, 0.03*8 -- texture scaling
cube:mapTexture(tex, texsx, texsy) -- (texture,sw,sh)
cube:setPosition(-0.2*8, 0.17*8, -0.05*8)
cube:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
scene:addChild(cube)

local sphere = D3.Sphere.new(2*8, 0.12*8) -- (steps,radius)
sphere:mapColor(0x55ff00) -- (color,[alpha=1])
texsx, texsy = 0.01*8, 0.01*8 -- texture scaling
sphere:mapTexture(tex, texsx, texsy)
sphere:setPosition(0.1*8, 0.12*8, 0.07*8)
sphere:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
scene:addChild(sphere)

local cylinder = D3.Cylinder.new(2*8, 0.1*8, 0.25*8) -- (steps,radius,height)
cylinder:mapColor(0xffaa00) -- (color,[alpha=1])
texsx, texsy = 0.05*8, 0.05*8 -- texture scaling
cylinder:mapTexture(tex, texsx, texsy)
cylinder:setPosition(0.3*8, 0.2, 0.15*8)
cylinder:updateMode(D3.Mesh.MODE_LIGHTING + D3.Mesh.MODE_SHADOW)
scene:addChild(cylinder)

-- light setup
local lsx, lsy, lsz = 0.4*8, 0.8*8, 0.4*8 -- light source position
local ltx, lty, ltz = 0.0*8, 0.0*8, 0.0*8 -- light target position
Lighting.setLight(lsx,lsy,lsz, 0.35) -- (x,y,z, ambient)
local pd, fov = 3*8, 7*8 -- 5*8, 6*8
Lighting.setLightTarget(ltx,lty,ltz, pd,fov) -- (x,y,z, projection distance,fov)
Lighting.computeShadows(scene)

-- game loop
stage:addEventListener(Event.ENTER_FRAME, function(e)
	cube:setRotationX(cube:getRotationX()+8*8*e.deltaTime)
	sphere:setRotationY(sphere:getRotationY()+9*8*e.deltaTime)
	cylinder:setRotationY(cylinder:getRotationY()+10*8*e.deltaTime)
	Lighting.computeShadows(scene)
end)

I am out 2

Please have a look at the Shapes Library V2.

You are strongly encouraged to mess with the code.

Bye for now!


Libs3D