VMFramework

VMFramework is a reusable Unity 6.4 framework package for VM233 projects. It contains shared gameplay architecture, configuration tooling, UI panel infrastructure, localization helpers, resource management utilities, map/tile helpers, editor tooling, and optional FishNet integration.

Installation

Add the package through Unity Package Manager using the Git URL:

https://github.com/VM233/VMFramework.git

For a fixed revision, use:

https://github.com/VM233/VMFramework.git#<commit>

Package Name

com.vm233.vmframework

The package keeps the existing assembly name:

VMFramework

Requirements

The package declares Unity registry dependencies in package.json for Addressables, Localization, Input System, TextMeshPro/UGUI, Tilemap Extras, Visual Effect Graph, and Newtonsoft JSON.

These external packages or plugins must also be available in the consuming Unity project because the current VMFramework.asmdef references their assemblies:

• VM Common Preset (com.vm233.common-preset 1.1.0 or newer)
• VMCore (com.vm233.vmcore or an embedded Assets/Plugins/VMCore copy)
• VM Odin Extensions (https://github.com/VM233/VMOdinExtensions.git)
• UniTask (com.cysharp.unitask or an embedded UniTask copy)
• Odin Inspector
• FishNet, when using FishnetExtension

BattleIdle currently supplies these dependencies from its project manifest and embedded plugins.

Because VM Common Preset is distributed as a Git package, consuming projects must pin its Git URL directly in Packages/manifest.json; the semantic dependency in this package only expresses the required version to Unity's resolver.

Layout

• Main: core runtime, editor tools, JSON helpers, UI panel infrastructure, configuration, game logic architecture, localization, resources, timers, and procedures.
• MapExtension: tilemap, grid map, map utilities, and tile config support.
• FishnetExtension: optional FishNet networking integration.
• Experimental: experimental framework code.
• GameResources: package-owned fonts and script templates. Runtime project global setting assets are expected under Assets/GameResources/Configurations/GlobalSettings.

Manager Containers

ManagerCreator owns the root ^Core object in the active scene. Manager category containers are resolved only among the direct children of that root. Business and configuration hierarchies may therefore reuse category names such as Audio without being moved or treated as manager owners.

Editor Project Settings

Open Edit > Project Settings > VMFramework to configure the project-relative folders used for GeneralSetting assets and Game Prefab wrapper assets. The values are stored in ProjectSettings/VMFrameworkEditorSettings.asset and are available directly to editor tooling; they do not depend on VMFramework manager creation, global-setting loading, Addressables, or scene initialization.

Framework maintenance commands are available from the Unity menu:

• VMFramework > Global Settings: check, locate, create, move, and address settings.
• VMFramework > Game Prefabs Tools: collect providers, remove empty wrappers, and move wrappers to the configured folder.

Projects upgrading from the legacy EditorSettingFile should copy any non-default folder paths into Project Settings, then remove the old EditorSettingFile.asset, its Addressables entry, and the EditorSetting scene component. Those legacy objects are no longer configuration authorities.

Common Presets

Common Preset runtime types, Odin drawers, registration, and Project Settings ownership now live in the independent com.vm233.common-preset package. VMFramework retains only its PriorityDefinesPreset declaration and consumes the package API.

Projects upgrading from VMFramework 2.x should install VM Common Preset and VMFramework 3.x in the same Package Manager resolve. Configure existing preset asset references directly in ProjectSettings/VMCommonPresetSettings.asset through Edit > Project Settings > VM Common Preset; the legacy VMFramework CommonPresetGeneralSetting asset is no longer an authority.

Game Editor displays a virtual Common Presets branch under Core Runtime. Its children mirror the ordered Project Settings list and open the concrete preset assets; neither the branch nor its items are serialized into CoreSettingFile.

Logic Tick Simulation Phases

LogicTickManager publishes one ordered deterministic step:

1. OnPreTick
2. OnTick
3. the current OnNextTick snapshot
4. OnPreSimulationTick
5. OnSimulationTick
6. OnPostSimulationTick
7. OnPostTick

Simulation command producers should use OnPreSimulationTick, the single simulation owner should use OnSimulationTick, and achieved-state or collision observers should use OnPostSimulationTick. Actions registered from simulation callbacks remain queued until the next logic tick.

Use TickDeltaTime for per-step simulation math. It remains the immutable admitted duration throughout the current tick even if a callback changes TickGap; outside a tick it reports the active gap for the next admission. Use TickInterpolationAlpha for presentation interpolation. AdvanceTime is available to deterministic clock owners and tests; it uses the active TickGap configured through SetTickGap.

State Clone Contexts

StateCloneContext is an immutable, allocation-free tag set passed through IStateCloner and IStateCloneable. Each module owns its clone semantics by registering tags once in static fields:

public static readonly StateCloneTag CustomBehavior = StateCloneTag.Create();

Root callers can build a context from stack memory:

Span<StateCloneTag> tags = stackalloc[] { CustomBehavior };
var context = new StateCloneContext(tags);
var clone = source.GetClone(context);

Nested producers use context.WithTag(tag); consumers use context.HasTag(tag). VMFramework defines only StateCloneTags.OwnerStateIncluded, which its Container clone path adds when cloning items together with their owner state. Projects may define their own tags without changing VMFramework. Tags are process-local, must not be serialized, and are limited to 64 registrations. Use StateCloneContext.Empty when a root clone has no tags.

Projects migrating from 1.x must replace StateCloneHint parameters with StateCloneContext, replace isNested = false roots with StateCloneContext.Empty, and replace nested boolean mutation with explicit WithTag production and HasTag consumption.

Notes

• This repository is now a Unity Package Manager package root, not a full Unity project.
• .meta files are kept so Unity asset GUID references survive the move from Assets/VMFramework to a Git package.
• JSONConverters was removed from VMFramework; framework code no longer depends on JSONConverterExt.