Name: ConsoleCommands
Version: 1.1
Date: 4/5/2017
Category: Utilities
Requirements: Oblivion Patch 1.2.0.416, Oblivion Script Extender (OBSE) v20 or later
Author: Tiawar



[General]

ConsoleCommands - as the name suggests - is an OBSE plugin which adds some console/script commands to the game.
These are mostly commands I made for myself but which may be useful to others. More commands may be added in the future.
The majority of these commands was made to be used from the console, but many can be used from scripts as well.
Before using any of the commands make sure you read the explanation for each command which may contain notes about
possible limitations and/or quirks if the command is not used correctly.


[Install]

1) Extract the files to a temporary location.
2) Copy the files in the Data folder to (install folder)\Oblivion\Data\


[Uninstall]

1) Delete the files/folders associated with the mod.


[Usage]

Commands can be used from the console or in scripts.
The Ini file associated with this plugin allows some additional configuration. (See section [Settings])


[Source Code]

The included source code (separate download) gives you an overview of the locations in the engine that will be patched
as well as a general insight into the implementation of the commands themselves.
However, it is currently NOT possible to compile the plugin from the code as it is missing the project that recreates
the game engine classes and maps functions to memory addresses.
This project is HUGE and currently not for share (not in a sharable state anyway...).


[Settings]

In the current version (1.10) the ini file only has one setting.

General settings (Section [General]):

1) sUserLogPath

OBSE plugins usually create their log files in the Oblivion game folder. By default, ConsoleCommands will create a log
file in the game directory as well. However, with this ini setting you can specify an alternative log file path to which
log output will be written. Note however, that the default log file will still be created for the initial messages (two
at most) and in case the specified user log file path is not valid. If the redirect was successful all subsequent messages
will be written to the new file. This may be especially useful for users who installed the game on an SSD drive and therefore
prefer to limit the amount of data that is written to the game folder.
The specified path should contain the file name and file extension.


[Commands]

1) GetCCVersion
---------------

This is just a simple command to check the current version of the ConsoleCommand plugin that is currently installed.
Note: If this command is called from a script the return value is an integer which represents the current version multiplied
by one hundred. (e.g. v1.00 returns 100)


2) AddDebugNote [AddDN] (message:string)
----------------------------------------

This command is primarily for (landscape) mod authors an patch writers. On of the (imho) most overlooked commands in the game is
called 'BetaComment'. By specifying a log file path in the Oblivion ini file you can target an object in the console and use this
command to add debug information about that object to the log file. These messages can be used later to fix certain problems with
the objects you found while playing. The only thing I don't like about the BetaComment command is the actual message it writes to
the log file. The message contains rather useless (for non-devs) info about the computer's current user but not even form IDs for
the selected game objects.
AddDebugNote basically does the same as BetaComment, only the added info text is different.
To use this command, type 'AddDebugNote' (or just 'AddDN') in the console followed by an arbitrary message. Unless the message is
just a single word make sure you enclose it with "". The message will then be added to ConsoleCommand's log file, together with
a time stamp and some auto-generated info about the currently selected object. If no object is selected then some information about
the player's current cell is added. E.g. typing

adddn "This rock is floating."

in the console whith the rock in question selected will add a line to the log file similar to this:
2017/03/04 16:19:17 [ DEBUG ] Command 'AddDebugNote': REFR:9D0406DD <RockGreatForest280> "<no name>" loaded from Better Cities Full.esp in world WRLD:0001C31C CheydinhalWorld "Cheydinhal" (28/22) at 118231.38/92345.28/7221.71: This rock is floating.

(Note: Editor IDs for objects are usually not included in the messages unless you installed a plugin which loads them.)


3) ToggleFlyCam2 [TFC2] (keepTFC:bool)
--------------------------------------

This command is just like the original TFC command but additionally 'freezes' the game while TFC2 mode is active.
To start TFC2 mode simply type 'TFC2' in the console. You can also start TFC2 mode while already in normal fly cam mode.
There a three ways to end TFC2 mode:
a) TFC
Since TFC2 is just TFC mode with time freeze using the normal TFC command will unconditionally end fly cam mode and resume the game.
b) TFC2
If you type 'TFC2' while in TFC2 mode what happens depends on the state of the game before TFC2 mode was started: If TFC2 mode was
started while in normal fly cam mode than time freeze will stop and you'll be back in normal fly cam mode at the current camera
position. If you started TFC2 mode while not in fly cam mode then the result is the same as in case a).
c) TFC2 1
The optional parameter only has a meaning when ending TFC2 mode. By appending '1' (in fact any non-zero number will do) to the
command time freeze will stop but the game will remain in normal fly cam mode at the current camera position regardless of the
state before TFC2 mode was started.

Step Mode: While in TFC2 mode you can advance the game by a single 'step' by pressing the Pause key on your keyboard.

IMPORTANT: The are some limitations associated with the time freeze effect for this command.
- Water 'movement' (wobble effect) is not stopped. (no idea where this is updated)
- You can equip/unequip items while in TFC2 mode. The change is visible immediately but current (frozen) animations may not match.
- You can use SetPos to move an actor while in TFC2 mode but SetAngle has no visible effect until the game is resumed.
As a workaround you can use SetPos after SetAngle to make the effect of any previous SetAngle command become visible.
- Like the normal TFC command, using SetPos or MoveTo on the player while in TFC2 mode will move the player but not the camera.
This can be a bit confusing at first. In general, moving the player too far away from the original position while the game is frozen
is not recommended.
- The game usually does not update animations 'behind' the player until they enter the camera's field of view. This may become apparent
when you move the camera around while the game is frozen (e.g. actors standing upright in bed). This can usually be fixed by advancing
the game a single step while the actors are in view.

NOTE: You can use all menus and the console normally while in TFC2 mode. I cannot guarantee that the time freeze works well with all
console commands in existence. Use the console with care while time is frozen. Feedback about incompatible commands is welcome.


4) GetSkyColor (layer:string)
-----------------------------

Returns the current RGB value for the specified sky layer. The layer name must be one of the following values (case-insensitive):

Ambient
CloudsLower
CloudsUpper
Directional
Fog
Horizon
SkyLower
SkyUpper
Stars
Sun
Sunlight

'Directional' and 'Sunlight' are just two names for the same layer. The current RGB value for the layer is what you actually see on
the screen. It is computed from the current and next daytime colors for the current weather and possibly the same values from a
transition weather (if active).
If this command is used from a script then the return value is a packed 32-bit integer: If the function succeeds the RGB values are
stored in the lower three bytes of the value. If the function failed (e.g. wrong layer name) the highest byte will be non-zero.
To check whether the function call was successful compare the return value to 0x01000000 (16777216). If the value is lower then
everything is ok and the lower three bytes contain the color value in the format BBGGRR.


5) SetSkyColor (layer:string) (red:int) (green:int) (blue:int)
--------------------------------------------------------------

Sets the RGB color value for the specified sky layer in the current frame. For an explanation about sky layers check the 'GetSkyColor'
command. Please note that the value you set only has an effect in the current frame (i.e. while the console is open). Once you close
the console the game will overwrite your changes with the computed values from the current weather and time. This command is therefore
only useful for testing weather colors in game. It can also be used to create special custom lighting in a scene for taking screenshots.
To do so, either change the sky colors while in TFC2 mode or use the TFC2 command after changing the colors but before closing the console.
While in TFC2 mode changes should stick until you end TFC2 mode and time resumes normally.
The color values use integer format (not hexadecimal) and must be in range [0,255].
Note: All SetSkyColor commands you enter will be logged to the ConsoleCommands log file so in case you found a nice color combination
you don't have to write the values down immediately.
Note2: Using this command from a script is completely useless. Even if you'd want to change colors only in the current frame, since
sky update in game mode happens after script processing your changes would be reversed before you see them.


6) Help2 (searchString:string) (filter:int)
-------------------------------------------

Lists all objects containing the specified search string in the name and/or editor ID. The search is CASE SENSITIVE!
You can add a filter (optional) to narrow the search.

Filters:
--------
0 All (default)
1 All (except actors)
2 Items all inventory items (ammo, armor, clothing, weapons, books, (carryable) lights, etc.)
3 Base Actors NPCs or creatures (NOT references!)
4 Actors NPC or creature references

10 Activators
11 Ammo
12 Apparatuses
13 Armor
14 Birth Signs
15 Books
16 Cells interior cells only; supports names and editor IDs
17 Classes
18 Clothing
19 Containers
20 Creatures
21 Creature Refs
22 Dialog Topics supports names and editor IDs
23 Doors
24 Eyes
25 Factions
26 Flora
27 Furniture
28 Game Settings
29 Globals only supports editor IDs
30 Hair
31 Ingredients
32 Keys
33 Lights
34 Misc Items
35 NPCs
36 NPC Refs
37 Potions
38 Quests supports names and editor IDs
39 Races
40 Sigil Stones
41 Soul Gems
42 Spells
43 Sounds only supports editor IDs
44 Weapons
45 World Spaces supports names and editor IDs

You can type help2 "?" in the console to get the list of all filters in-game.
If the search string contains spaces or does not start with a letter or digit you will have to enclose it with ""
for the game to recognize it as a string.
Generic searches will probably produce more results than the console can show.
You can modify "iConsoleHistorySize" in Oblivion's ini file to increase the number of lines the console remembers.
If the list is still too large you'll have to narrow down the search with a better search string or by using filters.
Many items or NPCs share the same name which makes it difficult to find the correct object.
Editor IDs can help distinguishing objects with the same name but the vanilla game only loads editor IDs for selected
form types. To get editor IDs for all types you can use my other OBSE plugin MessageLogger (enable editor ID loading in
the ini file).

Example: help2 Robe 18 Lists all clothing items which have "Robe" in their names.



[History]

1.1 2017/04/05 Added command: Help2
1.0 2017/03/07 Initial release.


[Credits]

Thanks to the OBSE team for the Oblivion Script Extender.
Thanks to Bethesda for creating Oblivion.
Thanks to TESNexus.com for the a one-stop-shop resource for authors and players.


[Legal]

This mod is provided as "is".
The author is not responsible for any damage done to your save game, game installation
or even your computer (though such an event happening is highly unlikely).
Use at your own risk.