Easy3d Manual - by Richard Evans

 Hello, and thank you for trying out my Easy3D Module for AGS 3.1.

AIM

 To easily generate 3D AGS games with no 3D knowledge using only the AGS Editor.

Installation

 Step 1. Copy E3d.scm and E3d.gue into your game folder.
 In AGS go to Script -> Module Manager. Click import, then select E3d.scm.

 Step 2. In AGS select GUIs. Then GUI -> Import another GUI... and select E3d.gue

 Step 3. In AGS select Characters. Then click properties. In the Edit Properties Schema right click and add a new schema.
    Name: E3dScale
    Description: Easy3d Scaling
    Type: Number
    Value: 100

 Step 4. In AGS select GlobalScript -> interface_click, then add the following lines of code, ignore the Obsolete comment.

    if (interface==gE3d.ID)
    {
        E3d.InterfaceClick(button);
    }

 Step 5. Ensure you call E3d.UnInit(); before any QuitGame(); functions. Normally, in AGS select GlobalScript -> on_key_press and change the line
     if (keycode==17) QuitGame(1); // Ctrl-Q
        to
     if (keycode==17) { E3d.UnInit(); QuitGame(1);} // Ctrl-Q

Step 6. Goto the General Settings screen and make sure the 'object-based scripting' box is UNchecked.
 

32-bit Textures: Easy3D requires all sprites and backgrounds are 32-bit textures and that Game Colour Depth is 32-bit (in Palette)

Usage - Basic

 3D Mode

 To make a room 3D, the room must have 3 animating backgrounds.
 The first is used internally and can contain anything, so just use the rooms background here.
 The second is used as the sky.
 The third is used as a tiled background to stop the rooms actual background repeating into the distance.

 In the room script - Player Enters Room (before fadein) , add the line

     E3d.Init();

 And that's it! Your room should now play as 3D.

 2D Parallax

 To add a 3D parallax area to your 2D room.

  In the room script - Player Enters Room (before fadein) , add the lines

     E3d.InitParallax(eE3dParallaxBottom,190);

 You need to supply the side of the screen (eE3dParallaxTop, eE3dParallaxBottom, eE3dParallaxLeft, eE3dParallaxRight), and where you want the parallax start from, in Room coordinates.

 Note: Any objects that are placed in the parallax area will automatically be moved about by Easy3D as if they were attached to the area.

Settings

 Once you have your new room running you will no doubt want to alter the 3D settings to get the best effects. To do this, make sure your game is running in Debug Mode. Now press the 'G' key. A GUI should pop up where you can adjust all the 3D parameters for that room by using the sliders.
 Clicking the 'Save' button will save the parameters for that room. Then whenever you reenter the room, its settings will be restored.

Usage - Advanced

 3D Mode

 E3d.Init(eE3dFlags Flags);
    eE3dFloor      = This room only has a 3D floor.
    eE3dSky        = This room only has a sky.
    eE3dFloorSky = This room has a floor and a sky (default)
    eE3dNo3D     = This room is not to be rendered in 3D

 E3d.UnInit();
    This is called automatically whenever the player leaves a room. You should only need to call this before your QuitGame(); to avoid any unreleased dynamic sprite warnings.

 E3d.Render();
    Force Easy3d to render the screen, for example if you want to use cross fading in rooms, you would need to put this at the end of the player enters room before fade in script. Normally you wont ever need to call this.

 E3d.InitHorizon(float Distance, int Graphic, optional int SkipAbove, optional int SkipBelow);
    Graphic will be rendered non scaled and centered vertically about the horizon.
    Distance=0.0, for infinite distance. At other values the horizon will scroll horizontally as if attached to the floor at Distance away from the camera. Graphic should therefore be horizontally repeating, or wide enough to completely cover the horizon from all camera positions.
    You can set SkipAbove and SkipBelow to tell Easy3D not to draw any sky or floor in this area above and below the horizon, for example if this area is covered by the horizon graphic.

 float E3d.Horizon; Specify where on the screen the horizon is.

 E3d.BuildWall(int RegionNumber, int Graphic, float Height);
    In the Editor go to Area - Regions, select an unused region and draw a straight line where you want the wall to be. Then add this function after E3d.Init(), specifying the Graphic and Height of the wall.

E3d.BuildWallHotspot(int RegionNumber, float Height, int X, int Y, int W, int H);
    As above, but instead of specifying a Graphic you can select an area of the Rooms background. Any hotspots in the area will be mapped onto the wall.

  E3d.BuildSurface(int RegionNumber, int Graphic, float Height);
    In the Editor go to Area - Regions, select an unused region and draw a rectangle where you want the surface to be. Then add this function after E3d.Init(), specifying the Graphic and Height off the floor, of the surface.

E3d.BuildSurfaceHotspot(int RegionNumber, float Height, int X, int Y, int W, int H);
    As above, but instead of specifying a Graphic you can select an area of the Rooms background. Any hotspots in the area will be mapped onto the surface.

 Note: Walls and Surfaces are drawn behind ALL the objects and characters in the room, and are drawn in the order of their region number, so a wall built from region 1 will appear behind a wall built from region 2.

  E3d.SetWallVisible(int RegionNumber, bool Visible);
    Use this to change the visibility of a Wall or Surface.

  E3d.LockCamera(bool State);
    Lets you control the camera directly without it automatically following the player character. The Cameras coordinates are the same as the Room Coordinates, except y and z have been swapped round as is the convention in 3D, and always looks Vertically up the room background. Once you have locked the camera you can alter its values directly.
        float E3d.CameraX; - Camera X position (or Room X position)
        float E3d.CameraY; - Camera Height
        float E3d.CameraZ; - Camera Z position (or Room Y position)
        float E3d.CameraPerspective; - Distance from the Camera's 'eye' to the screen, in screen units.
        float E3d.CameraAspect; - Horizontal scaling
        float E3d.CameraDistance; - Distance of camera from the player
        float E3d.CameraMaxZ; - In room y coordinates this is lowest line of the background that can be seen.
        float E3d.CameraClipZ; This is how close things can get to the camera before they stop being drawn. (default 10.0)
 

  Character* E3d.CameraCharacter; - The character the Camera will automatically follow, usually this will be the player.

  float E3d.ObjectZoom; - Global scaling value for all objects. Individual objects can be scaled by changing their E3dScale property.

  float E3d.CharacterZoom; - Global scaling value for all characters. Individual characters can be scaled by changing their E3dScale property, or by using the walkable area scaling.

  String E3d.SkyMessage; - The player will say this if they look at the sky.

  E3d.SetSpeech(eSpeechStyle SpeechStyle);
  E3d.RoomSpace();
  E3d.ScreenSpace();
    Easy3D works best if you use the Sierra-Style speech.
    If you want to use LucasArts-Style then you have to be aware of two other functions. E3d.RoomSpace() and E3d.ScreenSpace(). Basically if you want any of the characters to say anything, you must call E3d.ScreenSpace(); before they speak, and if you want to do anything using character room coordinates you must call E3d.RoomSpace(); beforehand. You can assume E3d.ScreenSpace(); has been called before any script functions, so if your function is just player.Say("Hello"); you wont need to call E3d.ScreenSpace(); first. Example script;
 

    #sectionstart object7_a // DO NOT EDIT OR REMOVE THIS LINE
    function object7_a() {
        // script for Object 8: Look at object
        player.Say("Just a couple of rocks.");
   
        E3d.RoomSpace();
        if (Region.GetAtRoomXY(player.x,player.y)==region[2]) {
            E3d.ScreenSpace();
            cStone.Say("help me");
            player.Say("Who said that?");
        }
    }
    #sectionend object7_a // DO NOT EDIT OR REMOVE THIS LINE

  E3d.Reset();
    Revert to default values.

 

 Files
 
When you save the setting for a room they appear in your game folder as E3dnnn.dat, where 'nnn' is the room number. You must remember to include these in the final compiled game folder. To keep things tidy you can set up an folder called E3d and put all the E3dnnn.dat files in there.