XML:ONLV: Difference between revisions

===The master XML file===

The master XML file's name determines the BSL folder name and the AKEV and ONLV file names in the output folder. File paths in the XML can be either absolute or relative.

* ONSK name in <Sky> (in Windows, this can be a fake name; does the Mac need actual ONSK files?)

* ONLD file for the new level; read [[Making_a_mod_package#Mod_Info.cfg|HERE]] about making sure your level is unlocked (accessible on the Load Game screen)

!width=120px| Content type

! Description

| The master XML file can link to other XML files. Most of them will be [[OBD:BINA/OBJC#OBJC_types|BINACJBO]] files. The file type is declared inside the file, so the file name itself doesn't have to contain the type. Ergo, "BINACJBOCharacter.xml" can be given a simpler name like "Character.xml".

Some resources used by those XML files can be found in a '''shared''' folder. OniSplit copies textures and "physics" objects into the output folder; furniture objects will be integrated into the AKEV. Unused resources in the shared folder will be ignored. That way the final level archive or AE package contains only the necessary files, saving disk space for the end user.

In the demo are various subfolders in the '''shared''' folder: consoles, doors, furniture, triggers and turrets. These file types do not need their file prefixes: CONS, DOOR, TRIG and OFGA. OniSplit will recognize them nonetheless.

CJBO files '''need relative paths to the resource instead of just file names'''. Taking consoles, for example: a standard export to XML gives you "console_data". But to use the shared resources these must be paths like "'''consoles/console_data.oni'''" as they are stored in '''shared/console/'''. Note how the demoed '''shared''' folder is placed next to the [http://mods.oni2.net/node/299 project ("lab")] folder and the XML master file points to it using "../shared".

| informational (space for notes)

: [[#<Model>|env_show ID 1]] (use 0 to hide)

: [[#Breakable glass with BSL recognition|env_broken ID1 [ID2]]] (if a second ID is supplied then objects in the range ID1..ID2 get counted; "3001 3018" would cover 18 objects)

: [[#Texture exchange|env_texswap ID texture]] (no file prefix/suffix allowed)

: [[#env_shade|env_shade ID ID R G B]]

Static objects store their ID in [[XML:AKEV#IDXA_.28quad_group_id.29|one of AKEV's IDXA instances]].

For a Google SketchUp BNV tutorial see [http://oni.bungie.org/forum/viewtopic.php?pid=36760#p36760 HERE].

Textures that aren't power of two (2^x) or bigger than 512 will be resized. For example, 2003x2000 will become 512x512.

: [[XML:BINA/OBJC/MELE|Melee.xml]] (overrides global MELE; not used in vanilla levels)

: [[XML:BINA/OBJC/CMBT|Combat.xml]] (overrides global CMBT? not used in vanilla levels)

This is a trimmed-down version of the master file '''lab.xml''' from the demo. It's meant to give you a first impression. We might upload a smaller demo someday with all features nonetheless.

The motorcycle has here scripting ID 9. You can show and hide the object with the BSL command '''env_show''', where the second parameter means true or false. '''Never use 0 as an ID''' because it won't work.

EdT demonstrates env_show [https://youtu.be/Em6wa5JTQNM here]. Note how the objects have collision.

* destructible walls like in Deus Ex: Human Revolution (trigger volume, replacing punch anim with punch-through-wall anim)

* grids in front of ventilation shafts (a small door object could be an alternative)

* managing object groups with trigger volumes (save multiple objects in one DAE file)

If the objects appear to flicker then we could replace the hide_all_object_groups() function with individual TV exit functions.

'''Mod Tool versus SketchUp'''

:'''In SketchUp''' you can group objects which enables you to easily duplicate all objects inside a group and to scale/rotate/translate them all together.

Either use the Explorer (A) or the Schematics (B) to create a hierarchy.

:(A) In the Explorer window, drag and drop one or more objects onto another one.

:'''Mod Tool: caution when saving to DAE!'''

:A normal selection won't do. You have to select the object tree to successfully save a hierarchy. This is the same way that you do it with Oni characters.

Let's say there are two groups. If an edit is made to one mesh, the clone in the other group is instantly changed the same way.

So that's a smart group. In SketchUp this is named "component". In Mod Tool it's named ???.

:(Can be imported from SketchUp DAE file but causes a crash when re-saving. I guess a script is needed to do the job.)

Broken environmental objects can be recognized by the BSL command ''env_broken (ID_1, ID_N)''. However, this requires additional code to work.

  if (inside_target_function eq 0)

Player enters the TV, targets_gone() gets triggered. The variable "inside_target_function" should be 0 by default, so we will enter the "if" block. Next, we can assume that the player didn't destroy all glass objects, so "num_broken" will be less than 18; thus, targets_are_not_gone() gets called.

The TV function targets_gone() ''would'' be triggered every frame, but targets_are_not_gone() creates a delay between checks: the TV gets deactivated for 60 frames. Then the TV becomes enabled again and will start anew until all glass objects got destroyed or player left the TV.

In this case the targets_gone() function will do nothing because "inside_target_function" was set to 1 by the first call.

BSL command supported on Windows and Mac:

Might be useful to switch on/off static and animated textures. (News broadcast screen: running or off or smashed. Lava stream: flowing or stagnating or cooled down. Etc.)

If we remove "_color" from the object, the shadows will be gone next time we import the tower.

If there's no vertex color property, the first usage of Shift + W will create that property. But you can also manually create it via Property > Color under Vertices Map.

To get general shading/lighting you can set up light sources. "Infinite" lights are useful for global lighting, while "Light Box", "Point", "Neon" and "Spot" are more suitable as local light sources. They can be accessed via Primitives > Light.

By default a Mod Tool scene has one Infinite light, but it doesn't shine in every direction so you might want to add more Infinite lights. Let's say one Infinite light for each direction (+X, -X, +Y, -Y, +Z, -Z) with an intensity of circa 0.25 (night) or 0.75 (day).

The illumination of those lights can be integrated into the vertex color property. There's some information [http://oni.bungie.org/forum/viewtopic.php?pid=29089#p29089 on OCF here]; the quoted information is in triplicate, so don't get confused by that: at first it's detailed, then summarized, then as a checklist.

* Under Surface Color, choose Enable, then in the box below select Vertex _Color; if that option does not appear, click on the New button next to it

* Under Map, select Illumination only

: [http://mods.oni2.net/system/files/vertex_color_script.txt There's a script here]<!--http://mods.oni2.net/node/352--> which can apply vertex color and render maps to all '''selected''' objects. Load it into the script editor with Alt + 4 and hit F5 to run it. (Be sure the script's language was set to VBScript.)

If you use '''env_shade''', use it with caution. It completely overwrites the vertex coloring.

A drawback of this method, AKA shadow maps, is the high number of [[XML:BINA/TMBD|TMBD]] changes and new textures for every wall, requiring a lot of memory. How to create shadow maps:

** Can be used to replace original texture

* "Illumination only": output a texture that only contains the shadows

** Can be used on a new overlying, transparent surface

With this approach there are two meshes, whereby the shadow effects on one mesh get drawn in front of the regular level texture.

Compared to the "baked lightmaps" method, this needs more polygons of course. And these polygons are transparent, which is a problem with Oni's limited rendering ability for such textures. However, standalone lightmaps only need a few new textures if used wisely.

Read [[Lightmapping levels]] to learn more.

The Rooms tag is mandatory. It contains an import path to BNV and ghosts (*.dae) which are used to create pathfinding grids. For information on the binary data behind this, see [[OBD:AKVA|HERE]].

Sample code from the master XML file:

* '''BNVs''' are '''volumes''' (sometimes also named '''rooms''') that have a pathfinding grid assigned to them.

* For practical reasons you only need '''floors and ramps''' to build a BNV. (As seen [http://edt.oni2.net/images/Hideout_BNV.jpg HERE.])

** A BNV polygon can consist of 3 or more points, but it's recommended to use '''shapes with 4 points''' because the other shapes usually waste more grid space. At the moment you can import only '''[[wikt:Convex|convex]]''' shapes.

* Secondly, there are so called '''ghosts''' (vertical quads) that connect '''neighboring BNVs'''. AI can only transit from BNV to another through ghosts.

: OniSplit gives error messages for ghosts that don't have 2 neighboring BNVs, for example:

  BNV Builder: Ghost 'grid2' has no adjacencies at <-72,41 1,999 -166,6> and <-71 1,999 -168,21>, ignoring

* Horizontal distance from room to ghost: 1

* Vertical distance from room to ghost: 18

* Ghost's horizontal dimension must be greater than 0

* Under optimal circumstances, pathfinding works on a plane that is +4 world units above or -0.5 below the pathfinding grid

* Normally characters can't pass over low vertical walls such as stairs/curbs if those don't have a ramp under them; near ground level (Y=0) is an exception where characters are allowed to step on a plane that is 4 world units above pathfinding grid; higher planes need a ramp

* Maximum angle of ramp you can go on is 70°; higher angles will make characters fall through to their death (in those cases you might want to add invisible walls/boxes to prevent them from touching the ramp)

* During pathfinding calculation, OniSplit creates a new folder called "temp" and a subfolder "grids". There is a file named "''levelname''_grids.dae". That file contains rooms with textures called "bnv_grid_''N''.tga" which mark obstacles in the pathfinding grid. Ghosts will have a transparent texture "'''_marker_ghost'''.tga". You also get these when you export a level. Transparent ghosts make it easier to see the rest of your level if you have many of those planes.

* In Mod Tool, ghosts and rooms can be grouped under a null object. Right-click the null object to select all its children, then use "Selection Only [x]" as your saving option. That way all the planes can be quickly saved to a *.dae file.

* You can influence the pathfinding creation of dangerous zones using danger quads. Read about those [[#Marker textures|HERE]].

* Another kind of influence is the [[#<Model>|gunk flag]] IgnoreGrid. It can be used to tell OniSplit to ignore the object during pathfinding creation. The grids in that place will be white.

[[Image:Pathfinding_grid.JPG|thumb|200px|right|'''ai2_showgrids = 1''' in action]]

:: shows number of BNVs the player is standing on

:: spawns a friendly Striker that follows the player if possible, makes also pathfinding grids visible

:: Striker stops following you

:: Striker follows you again

Pathfinding works on slightly uneven ground as long as the polygons are 0.5 world units beneath or 4 world units above the BNV.

For greater surface irregularities, we can use a trick:

* The problematic polygons must be saved to a DAE file and then referenced in the model section as an individual object.

* Additionally we create a plane (invisible if necessary) under the object so that Oni doesn't think there's a hole.

* The ghosts must be taller than the highest polygon to be walked on. (This has been tested up to a height of 2,000 world units.)

'''Symptoms of too-small ghosts'''

B) AI loses PF ability if the tracked enemy performs animations that are outside of the pathfinding volume. Here's a video (<nowiki>https://youtu.be/vfKPzP5hiCo</nowiki>, dead link) showing these symptoms.

Let's say you have a BNV, tall ghosts, and a GridIgnore-flagged hill with trees and bushes and stuff.

Why do AIs run up against the trees?

: '''Problem:''' There are no red/orange grids that limit the AI's movement. Normally, objects will produce red pathfinding squares around them. But objects that are 20 world units above the BNV are ignored just like objects with the IgnoreGrid flag.

The ground is sometimes not solid, and the player and AIs are falling through it.

[[Image:OniBrowser.jpg|thumb|200px|right|OniBrowser displaying level geometry plus PF and ghosts.]]

** The original ghost quads can't be seen; per Neo, "they are not included in the octtree and bsp tree"

** To see them you must use the -debug option in the level creation command (available with OniSplit '''v0.9.93.0+''')

Not all debugging/testing needs to be done in Oni. There is also a [http://mods.oni2.net/node/256 program] (Windows only) which can display the whole level.

For example you can load an AKEV*.oni, select the level name, and use the hotkeys [B] and [P] to display BNVs and ghosts.

After all testing is done, you should compile the level a last time without the -debug option.

[[Image:pathfing_creation__merge_polygons_to_fix_connections.jpg|thumb|200px|right|Fixed PF in compound level after underground construction...]]

It can help to merge polygons to one object and merge their edges. These become white. (Outer edges are blue.)

====<Textures>====

The [[#textures_tag|textures tag]] is mandatory.

AKEV textures will be imported by the master XML file automatically; you don't need to add them to that file.

: With OniSplit v0.9.82-93.0, the textures' formats will be DXT1 and (for transparent ones) BGRA4444.

: With OniSplit v0.9.94.0+ the textures' formats will be BGR and (for transparent ones) RGBA.

To change the default texture import format, use the Texture'''s''' tag. (Possible with OniSplit v0.9.94.0+.)

To change the format/flag/gunk flag of a specific texture, use the Texture tag.

* Use the gunk flag "TwoSided" to make surfaces visible from both sides.

* If the texture comes with the gunk flag "NoCollision" then all objects with that texture will have no collision. Characters would fall through it.

Transparency and no collision together would make sense for a water-like substance. The Vago Biotech level uses this approach for the area with green toxic waste.

[[Image:AKEV_single_object_multiple_textures_ingame.png|thumb|200px|right|'''Figure 3'''<br>blue: two-sided<br>glass: two-sided and transparent<br>random metal: no flag (one-sided)]]

It's also possible to set this in Mod Tool. For TwoSided-ness, use one image source for diffuse and transparency. (It won't work with two image sources even if both sources use the same image.)

For transparency you must additionally use the three checkboxes:

'''One texture per object'''

Furniture and Physics objects are allowed to have only one texture per object. AKEV core geometry can have one texture or multiple textures – that's up to you to decide.

'''Answer:''' Assuming you are using Mod Tool the procedure will be as follows. Repeat this for each cluster you create (except for projection). See also '''Figure 2 and 3'''.

* Select some polygons

* Go to Material > Phong

* Hit [7] to open Render Tree

* Add a texture and connect "Image" with "Phong", choose "diffuse" as illumination mode

* Double-click "Image" to open Material page

* In the Texture Projection section, click on "New" and choose a suitable projection

** Do this only if there isn't a projection in the "Texture_Coordinates_AUTO" cluster yet

* Choose the texture and UV, then fine-tune the UV via Alt + 7

Caution: textures will be fixed to one set of flags. You can't use the same texture A for a one-sided cluster/object B and a two-sided cluster/object C. You would need to create a differently-named clone of that texture and apply that to cluster/object C.

Marker textures are used to import certain objects with special flags. Import those objects alongside [[#<Model>|AKEV core]] geometry.

Marker textures aren't imported automatically. Add those textures to the final package or plugin yourself, e.g. with some sort of script.

Pathfinding grids have different colored squares with different meanings.

* green light - near wall

* green - semi-passable

For detailed information on colors, see [[OBD_talk:AKVA/0x24#EFFECTS_of_various_pathfinding_grid_tile_types|HERE]].

Normally, OniSplit decide how to color the grids. But it's possible to add your own danger quads to fine-tune zones of higher danger. Those orange areas will be generated with the 4 different blue borders around it.

<!-- Originally this is only used for level-bounding invisible walls? -->

AIs can get stuck in detailed geometry. This can be prevented with collision boxes. In-game the box will be invisible, but has collision so characters can't get through. The pathfinding grid will be red where it comes in contact with the box; the red is followed by a light green and then regular green.

[[XML:OFGA|OFGAs]] use the COLLISION texture. Onisplit doesn't automatically apply gunk flags to it. You need to use XML tags for that. Typically it would be <GunkFlags>Invisible NoObjectCollision</GunkFlags>

'''Stairs'''

Texture: '''_marker_stairs'''

Normally, characters can't move on stairs because they contain vertical rises. In this case you can use a sloping quad that is above or inside the staircases. It's possible to set the desired flags in the <Model> section, but doing so and exporting these self-made stair ramps is wasted time. Simply apply _marker_stairs to that quad and characters will be able to move on that surface.

Resulting flags: Stairs Transparent TwoSided Invisible NoObjectCollision NoOcclusion

This has no effect on pathfinding creation. Regularly-textured stair geometry (which intersects the marker quad) will be flagged as NoCharacterCollision.

'''Impassable'''

Resulting flags: Transparent TwoSided (<-double-check this) Invisible NoOcclusion

Impassable walls are very similar to collision boxes except that particles can also collide with them. The pathfinding grids will be also red, light green, and green.

'''Blackness a.k.a. jello fix'''

Texture: '''_marker_blackness'''

Resulting flags: TwoSided NoCollision

Simply black walls. No effect on pathfinding creation. The purpose of these walls in Oni is to block out areas outside of a level's outermost wall so that the Jello-cam cannot show the player other parts of the level when it escapes a wall. See [[Jello-cam]] for details.

'''Doors'''

Texture: '''_marker_door'''

Resulting flags: DoorFrame Transparent TwoSided NoCollision NoOcclusion