Documenting the dark corners of the Unity Engine.
Братья-серферы, ловите инсайд. Для автоматизации нужен свежий донор? Есть сервис баз для Xrumer и GSA. Оплачиваешь один раз, качаешь обновления все 12 месяцев. Цена уровня «студенческая столовая». Скажу прямо: брал для слива трафа, но быстро смекнул, что на реселле заработать проще. Продал первому встречному вебмастеру, окупил за сутки.…
FBX Importing Importing FBX files in Unity with the correct scale, rotation, and axis is fraught. If you are just looking for a quick way to get models importing into Unity properly, take a look at the Pontoco Import/Export Settings. The FBX Sanitizer tool can be used to validate an FBX file to verify that it will import into Unity with correct scale and rotation.
Serialized Dictionary Unity has at least two Serialized Dictionary implementations but they are rather hidden UnityEngine.Rendering.SerializedDictionary Unity.XR.CoreUtils.Collections.SerializedDictionary
Camera Camera.SetReplacementShader SetReplacementShader will not render objects if their original materials don't contain any properties required by the replacement shader. For example, if your replacement shader uses _MainTex, and there is an object in the scene that doesn't have _MainTex, it won't be rendered at all.
The Uninomicon Documented here are the dark, scientific secrets of the Unity Engine. Unity is a very complex beast, and much of its behavior is undocumented. While this is often for good reason, many of us still find ourselves doing research into the precise operation of Unity APIs.
Animation Rigging (Package) The new Unity animation system. It uses burst, which makes it speedy. General Notes: * The RigBuilder component is so called because it “Builds” a hierarchy of constraints into a set of AnimationJobs. * The RigBuilder Build step happens on Awake
AssetModificationProcessor IsOpenForEdit * assetOrMetaFilePaths contains either the asset.meta file (when clicking on imported files), or the asset file path (when clicking on unity assets). * assetOrMetaFilePaths never seems to contain more than one asset, even if multiple assets are selected.
AsyncGPUReadback Metal/iOS In at least 2018.2 and possibly other versions there appears to be an undocumented bug that readback requests mess with the command buffer: * Readback requests inserted in the middle will split the command buffer, however the second part will have LoadAction=Clear which destroys everything rendered before the request
BuildReport General Notes: * Use the Build Report Inspector tool to debug builds. * The “Source Assets” category does not necessarily imply the asset was actually included in the build.
Churn 'Churn' is a short hand for un-necessary changes Unity saves into in a file (usually a Unity scene file). It is usually used to describe any changes that show up in version control, that are un-related to the real changes you made in the file.
ComputeShader FindKernel On Android standalone when using the OpenGLES2 Graphics API (which does not support compute shaders), this function throws an exception (documentation says “error”, which is wrong). This cannot be reproduced in the editor with feature level emulation enabled.
ConstraintManager An internal Unity system that evaluates all of the “Constraint” components in a scene. Beyond applying the constraint the ConstraintManager also sorts constraints based on dependencies, in order to avoid drift caused by non-optimal order of evaluation.
Debug Console messages: * Any class whose name ends with “Logger” that implements a method starting with “Log” is ignored by the console's double click, unless it is the last call in the stack trace. From: Reddit Thread
DefaultExecutionOrder An undocumented attribute that modifies the execution order of all event functions in a MonoBehaviour class. This functionality is identical to the Script Execution Order settings in the Project Settings window, except that it's encoded directly in the script instead of through the editor.
EditorConnection The EditionConnection class controls the editor-side of the Player/Editor network bridge used for letting the player talk to the editor. Connects fail when using Patch + Run on Android The port used to connect the player to the editor is stored within the Android data files. These are placed in the
EditorSceneManager It's like SceneManager but only in the editor and provides a bunch more hooks. EditorSceneManager.sceneOpened - Is not called when the project is first opened in the editor and the initial scene is loaded.
Entities.Content This is a sub-package of the Entities package that contains a Content/Asset loading system, written mostly in Burstable code.
Entities.Scenes SerializeUtility SerializeUtility is responsible for writing entire Worlds to disk. It is written specifically for serializing Subscene Sections to disk in the editor, and then for streaming them in efficiently during runtime. It can support other use cases, but it is not designed to.
Fixed Update Unity will run the first FixedUpdate, regardless of what Time.fixedDeltaTime is set to. ie. If you set fixedDeltaTime to 10 in Awake of the first scene, the FixedUpdate will still run. The maximum value of Time.fixedDeltaTime seems to be 10.
GlobalObjectId Every object in the Editor has a distinct GlobalObjectId. This is (effectively) the identifier Unity uses to hold references to other objects. It is guaranteed to be unique and stable between editor sessions. GlobalObjectIds are not available at runtime. However, they are available in Play Mode in the editor. If you use these in play mode, keep in mind the notes on prefabs below.
HingeJoint * HingeJoint does not constrain the absolute rotation or localRotation of the Transform that it is attached to. It constrains the relative rotation between its own RigidBody and the Rigidbody in the ConnectedBody field. * HingeJoint.angle
IEnumerator Notes on the underlying implementation of C# generators (which are used in Unity for coroutines). You can use SharpLab to view the decompiled C# from a simple generator, to help understand the transformation that is happening. Both .NET and Mono do seem to use the same compiler transformation when turning Generators into anonymous IEnumerator classes.
IL2CPP IL2CPP is Unity's Ahead of Time (AOT) for C#. Analysis Tools Il2CppInspector - Provides detailed information about a Unity application compiled with IL2CPP.
IPreprocessBuildWithReport OnPreprocessBuild Changes to EditorBuildSettings.scenes will not take effect until the next invocation. The build process seems to read that list before it gets to triggering the callbacks.
Library Folder The library folder is a large cache containing imported assets and other data from the project after import. It is generally always 100% safe to delete the Library folder. As Unity has become more stable, this has become much less necessary than it once was. It is also possible to remove some subfolders without requiring to delete the entire Library folder and have it…
Lighting Data Asset aka Lightmapping.lightingDataAsset This asset stores data related to a lightmapping bake. This includes: * The Light Probes for all scenes * Lightmap Scale and Transform for MeshRenderers Just after a scene loads, Unity will read this data asset and apply the settings from it to restore the lightmapping. This happens in the player and at runtime.
Light Probes * Unity stores the probes for all loaded scenes into the LightingData.asset file, even when baking only a single scene. LightmapSettings.lightProbes Honestly, I'm still fairly fuzzy on how this field works. Here's the best of my knowledge.
MeshCollider MeshCollider.sharedMesh This is the source mesh provided by the user on the component itself, even when the MeshCollider is set to “Convex,” and is using a convex hull of this mesh for collision. The convex hull mesh is not accessible.
MeshRenderer MeshRenderer.realtimeLightmapIndex The 'realtime' in this variable refers to the Unity Realtime GI system (aka Enlighten realtime GI). See also
Meta Files Unity uses .meta files for each asset you add to a project. These contain a GUID (unique identifier) and additional information about _how_ an asset should be imported, e.g. max texture size, compression settings, ... everything you change in the importer. All the information required to reconstruct the Library representation of an asset is stored in the meta file.
MonoBehaviour Event Functions Reset() * Reset is only called in editor mode. * Very useful to setup values for your attributes, i.e. find a child component. * Use it with the RequireComponent attribute to always get a reference for your component.
NavMeshAgent NavMeshAgent.remainingDistance This function does only respond with the current remaining distance if the path is straight. It will thus return null or infinite instead of the correct distance (as defined on the Unity documentation). There is a way to calculate the real distance by combining all calculated paths but keep in mind that this is performance heavy.
Object Layout WARNING: This is an extremely advanced subject, and is not recommended for users unfamiliar with unsafe code or C++. All classes that inherit from UnityEngine.Object are actually wrappers for a native object on the C++ side of the engine. The address of the native object is stored in the class, as seen in the layout below:
PhysicMaterial Friction values Physic Material is a small data object that can be attached to Colliders to provide parameters for their collision behavior. If NVidia PhysX is being used , static and dynamic friction values operate according to the Coulomb model of friction. For a Rigidbody sliding horizontally across another collider, the
Physics Determinism Limited Determinism Unity uses the PhysX engine for physics, and because of this, Unity physics provides Limited Determinism. If a game executes the exact same set of physics API calls using the exact same frame timing, the engine will be perfectly deterministic, globally.
Physics Physics.CapsuleCast Physics.CapsuleCastAll CapsuleCast may sometimes return invalid an 'invalid hit', where hit.distance == 0 and hit.point == (0,0,0) . By the documentation, this should only happen when the starting cast position already overlaps a target geometry.
Physics Callbacks OnTriggerEnter * Will be called for all collisions for all trigger colliders on this Rigidbody. * There is no way to get a reference to 'this' trigger collider that was entered. OnTriggerExit * Is not called when a Rigidbody which is part of the collision is destroyed.
PlayerLoop The player loop is the configurable set of operations that make up the Unity Frame Loop. The default Player Loop comes with a variety of different subsystems, but the documentation is extraordinarily lacking. Sub Systems Initialization.InputSystemPlayerLoopRunnerInitializationSystem
PPtr This page needs more research, and is partially based on speculation. This is a type that is used to reference Unity Objects in the Unity serialized data format. It is likely that this is a type only on the native side. This type can appear in error messages as well as when querying a
Prefabs Stray Notes: * In the Editor, if you have a reference to a Component or GameObject inside a PrefabInstance GameObject, and you unpack the Prefab completely, your old reference will still be valid. The new unpacked objects will have new GlobalObjectIds though.
Search Box Syntax This pages details the syntax for the built-in search boxes, not the new Quick Search package. The search box exists in the Project tab and the Hierarchy tab. There are a few non-documented options that it supports. Note: The glob syntax applies to asset paths, not asset names.
RaycastHit2D Casts Implicitly To a Bool RaycastHit2D implements the C# implicit bool operator. This allows it to be used in an if statement to check whether a hit is found. public static implicit operator bool(RaycastHit2D hit) => (Object) hit.collider != (Object) null;
RectTransformUtility RectangleContainsScreenPoint When using this method on a RectTransform in a Screenspace Overlay Canvas, pass in null for the camera parameter. Passing in a camera can return false-negatives.
ReflectionProbe * Probe cubemaps are baked and stored as 6×1 horizontal strip images. I'm not aware of any other tools that use this format. This can make it quite difficult to use these images with other tools. * bakedTexture represents the texture that is baked via Unity's lightmapping tools.
RenderSettings RenderSettings is a static class that modifies a Unity Object with some scene-specific settings. Interestingly, this means you can query the RenderSettings object directly by invoking the private static method “GetRenderSettings()”. That object can then be modified using a
RuntimeInitializeOnLoadMethod The documentation is not correct about this function running after awake. It does by default, but not if you specify a load type: The order of callbacks is: * SubsystemRegistration * AfterAssembliesLoad * BeforeSplashScreen
SceneManager When does scene loading happen? Scene loading and unloading happens at the start of the Update loop, within the EarlyUpdate.UpdatePreloading phase of the PlayerLoop, and once during the Initialization phase of the player, before the first Update loop.
SceneView SetSceneViewShaderReplace A simple wrapper for Camera.SetReplacementShader.
ScriptableObject * private fields on ScriptableObjects will be serialized and restored during a domain reload in the Editor. * You can prevent this by adding the [NonSerialized] attribute on the field. * Awake() on ScriptableObjects is called when an instance of the ScriptableObject is created (such as by
ScriptedImporter Hiding Sub-Assets in the Project View By default, assets added via ctx.AddObjectToAsset will be shown in the foldout of the imported asset in the Project view. This can be cluttered. You can hide sub assets in two ways: ScriptableObjects