Method for synchronizing domain language primitive behavior with machine-oriented documentation

Abstract

The application discloses a domain language primitive behavior and machine-oriented document synchronization method, and relates to the technical field of artificial intelligence native game engine. The method comprises the following steps: constructing an example package for each domain language primitive, wherein the example package comprises a runnable instance and a list, the runnable instance comprises an exposed excerpt with an identifier, and the list comprises an identifier set; checking whether all behavior branches declared by the primitive appear in the identifier set; obtaining a real running effect by running a probe scene and comparing the real running effect with a behavior result described in the exposed excerpt; checking whether the example package is configured with a behavior probe and whether a probe reason meets a preset condition; and obtaining the exposed excerpt according to the identifier set and rendering the exposed excerpt into a machine-oriented primitive document after passing the check. The application can ensure that the primitive document read by artificial intelligence is always a verified and executed real behavior projection, and the correctness of the generated result is improved.

Description

Technical Field

[0001] This invention relates to the field of artificial intelligence native game engine technology, and in particular to a method for synchronizing domain language primitive behaviors with machine-oriented documents. Background Technology

[0002] In the scenario of an AI-native game engine, the game logic is entirely described by declarative configuration data. The engine exposes a limited set of pre-compiled primitives, fixed to the compiler. These primitives are not used by programmers who individually review the source code; instead, a large language model reads the machine-oriented documentation and generates configuration data accordingly. AI's entire understanding of a primitive comes from the primitive's documentation rendering, not its actual implementation. Therefore, whether the documentation faithfully reflects the primitive's actual behavior elevates from a matter of engineering cleanliness to a fundamental issue of correctness that determines the quality of the generated code. In existing technologies, machine-oriented primitive documentation typically takes the form of handwritten prose, independent of the implementation. The documentation and the actual behavior are separate sources, silently drifting. In traditional engineering, primitive documentation describes the primitive's parameters, default values, enumeration values, written fields, and side effects. The documentation is another true source, independent of the implementation and handwritten. When someone modifies the primitive's implementation—for example, changing the default value, the semantics of an enumeration value, the target field of the action, or the return value of the value function—there is no mechanism to force synchronization of the documentation. The documentation now describes the old behavior, yet it continues to be fed to artificial intelligence as the source of truth. This drift is silent; compilation passes, testing passes, and the documentation is rendered as usual, only the content of the documentation is now incorrect.

[0003] To mitigate inconsistencies between documentation and code, engineering practices often employ solutions such as executable docstring tests, literate programming, component example galleries, or application programming interface (API) reference documentation generators. Executable docstring tests extract example snippets from documentation comments and run them as tests, but the runtime environment is a language-level unit or process, not a complete game engine backend that builds a real game world. Therefore, they cannot verify whether the physics, rendering, or event effects produced by running in a real engine match the description. Literary programming interweaves code and explanatory text in the same document, then extracts compilable source code, but the explanatory prose itself remains handwritten, unexecuted, and freely movable. Component example galleries showcase multiple uses of each component, with each story being a renderable, real-world component instance. However, the gallery displays human-readable visuals, lacking machine-readable, asserted behavioral contracts, and there's a lack of assertive bridging between the stories and the actual component behaviors. The application programming interface reference documentation generator extracts reference documentation from source code comments, but the semantic descriptions, examples, and default values ​​in the comment text are still handwritten prose that is not executed or verified and can be freely moved around.

[0004] The aforementioned existing technologies all suffer from the following drawbacks: The documentation and implementation are two separate sources; the documentation remains unchanged even if the implementation changes, and there is no mechanism to force the documentation to be highlighted, leading to silent drift. Outdated documentation for AI will inherit the same erroneous perception in all subsequent generation, resulting in widespread drift contamination. Handwritten examples arbitrarily omit behavioral branches; branches without examples are equivalent to undocumented branches, forcing AI to guess at them. Independent handwritten examples lack validation, execution, and consumption guarantees, gradually becoming syntactically and semantically outdated, or even completely ignored. Even if an example is executed, it only guarantees that the example runs, not that the actual behavior of the documented primitives remains unchanged. Existing executable documentation does not assert effects in the complete engine backend and the real game world, failing to capture behavioral drift that only manifests during actual runtime.

[0005] In summary, the technical problem to be solved by this invention is to provide a method for synchronizing domain language primitive behaviors with machine-oriented documents, so that each primitive document read by artificial intelligence is an excerpt projected from a real, minimal, runnable game after verification and execution, rather than an independently handwritten essay; each behavioral branch of the primitive is required to appear in a certain exposed excerpt; the running behavior of the primitive is asserted by a behavior probe that starts and runs a real game world from a complete engine backend, and once the behavior drifts, the probe immediately captures the drift as a test failure; the behavior probe is enforced by default for each primitive, and exceptions must be explicitly declared by the primitive list with specific reasons. Summary of the Invention

[0006] The technical problem this invention aims to solve is to address the shortcomings of existing technologies, specifically the problems of silent drift caused by documents and actual behaviors being separate sources, unguaranteed coverage of behavior branches, and the inability to capture semantic drift due to the default absence of behavior probes. Specifically, this invention provides a method for synchronizing domain language primitive behaviors with machine-oriented documents, as follows: 1) In a first aspect, the present invention provides a method for synchronizing domain language primitive behaviors with machine-oriented documents, the specific technical solution of which includes: For each domain-specific language primitive, an example package is constructed, which includes a runnable instance and a manifest that can be verified by the engine loading process; the runnable instance includes at least one exposed excerpt with an identifier, and the manifest includes a set of identifiers for the runnable instance; Obtain all behavior branches of the domain language primitive declaration, check all behavior branches, and generate a failure indication when any behavior branch does not appear in the identifier set; For example packages configured with probe scenarios, the probe scenarios are run to obtain the actual running effect. When an exception occurs while running the probe scenarios, a failure indication is generated; otherwise, the description behavior result is determined based on the exposure extract. When the actual running effect does not match the description behavior result, a failure indication is generated. For example packages without configured probes, determine whether the example package has configured a behavior probe. If the example package has configured the behavior probe, generate a failure indication when running the behavior probe fails. If the example package does not have configured the behavior probe, generate a failure indication when the probe reason content in the list does not meet the preset conditions. When no failure indication is generated, an exposure extract is obtained from the runnable instance based on the identifier set, and the exposure extract is rendered into a machine-oriented primitive document so that the large language model can read the primitive document.

[0007] The beneficial effects of the synchronization method between domain language primitive behaviors and machine-oriented documents provided by this invention are as follows: By constructing example packages containing runnable instances and manifests for each domain-specific language primitive, and using identifiable exposure extracts to encapsulate the primitive's usage within the runnable instances and manifests to record the set of identifiers, machine-oriented primitive documents no longer rely on independent handwritten prose but are projected from real runnable instances, fundamentally eliminating the possibility of AI reading unverified handwritten documents. Branch coverage guards check whether all behavioral branches of a primitive declaration appear in the set of identifiers, ensuring that each behavioral branch has a corresponding exposure extract, avoiding the problem of less common branches being missed and AI having to guess about branches not yet exemplified. Real-world execution is obtained by running probe scenarios. The effect is compared with the behavioral results described in the exposure excerpt, and semantic drift is transformed into a captureable failure indication, solving the problem of silent drift that cannot be detected when the behavior described in the document is inconsistent with the actual implementation of the primitive. By flipping the default guard, the example package without configured behavior probes is required to include probe reasons that meet preset conditions in the list, so that every primitive with assertable behavior must be verified by real operation. Behavior probes are changed from optional to mandatory, thereby systematically ensuring that the primitive document for machine is always a verified and executed projection of real behavior. The configuration data generated by artificial intelligence based on this document no longer inherits outdated or incorrect primitive cognition, improving the correctness of the generated results.

[0008] Based on the above solution, the present invention can be further improved as follows.

[0009] Furthermore, the engine loading verification includes: During continuous integration, an engine load check is performed on the runnable instance. If the check result is not zero errors, a failure indication is generated.

[0010] Furthermore, the exposure extract is defined by an exposure tag, which carries an identifier; the exposure extract contains usage fragments of the domain language primitives corresponding to the example package; the identifier corresponds one-to-one with the elements in the identifier set.

[0011] Furthermore, the operation mode of the probe scene includes: starting a complete engine backend and constructing a game world where physics and events work realistically, in order to obtain the realistic operating effect.

[0012] Furthermore, exceptions that may occur when running the probe scenario include: the process corresponding to the probe scenario crashing, timeout, or empty output; The described behavior outcome is determined by the annotations carried in the exposure extract, which record the time and purpose of the behavior described in the exposure extract.

[0013] Furthermore, it also includes: The probe scenario is listed as an independent test unit, which is not incorporated into the rapid unit test suite and is not included in the pre-commit hook; when the behavior probe corresponding to the probe scenario touches the corresponding domain language primitive behavior or touches the corresponding example package, the probe scenario is run manually, periodically or periodically.

[0014] Furthermore, it also includes: During application construction, the exposure extracts are compiled into a binary string constant table, so that the primitive document produces a consistent set of extracts in any running directory, and consistency checks are set to prevent the string constant table from drifting with the exposure extracts.

[0015] 2) In a second aspect, the present invention also provides a synchronization system for domain language primitive behaviors and machine-oriented documents, the specific technical solution of which includes: an example package construction module, a branch coverage guard module, a probe running module, a flip default guard module, and a document projection module; The example package building module is used to build an example package for each domain language primitive. The example package includes a runnable instance and a manifest that can be verified by the engine loading process. The runnable instance includes at least one exposed excerpt with an identifier, and the manifest includes a set of identifiers for the runnable instance. The branch coverage guard module is used to obtain all behavior branches of the domain language primitive declaration, check all behavior branches, and generate a failure indication when any behavior branch does not appear in the identifier set. The probe running module is used to run the probe scenario for an example package configured with the probe scenario to obtain the actual running effect. When an abnormality occurs when running the probe scenario, a failure indication is generated; otherwise, the description behavior result is determined according to the exposure extract. When the actual running effect does not match the description behavior result, a failure indication is generated. The flip default guard module is used to determine whether the example package has a behavior probe configured for example packages in scenarios where no probe is configured. If the example package has the behavior probe configured, a failure indication is generated when the behavior probe fails to run. If the example package does not have the behavior probe configured, a failure indication is generated when the probe reason content in the list does not meet the preset conditions. The document projection module is used to obtain an exposure extract from the runnable instance based on the identifier set when no failure indication is generated, and render the exposure extract into a machine-oriented primitive document so that the large language model can read the primitive document.

[0016] Based on the above solution, the present invention can be further improved as follows.

[0017] Furthermore, the engine loading verification includes: During continuous integration, an engine load check is performed on the runnable instance. If the check result is not zero errors, a failure indication is generated.

[0018] Furthermore, the exposure extract is defined by an exposure tag, which carries an identifier; the exposure extract contains usage fragments of the domain language primitives corresponding to the example package; the identifier corresponds one-to-one with the elements in the identifier set.

[0019] Furthermore, the operation mode of the probe scene includes: starting a complete engine backend and constructing a game world where physics and events work realistically, in order to obtain the realistic operating effect.

[0020] Furthermore, exceptions that may occur when running the probe scenario include: the process corresponding to the probe scenario crashing, timeout, or empty output; The described behavior outcome is determined by the annotations carried in the exposure extract, which record the time and purpose of the behavior described in the exposure extract.

[0021] Furthermore, it also includes: The probe scenario is listed as an independent test unit, which is not incorporated into the rapid unit test suite and is not included in the pre-commit hook; when the behavior probe corresponding to the probe scenario touches the corresponding domain language primitive behavior or touches the corresponding example package, the probe scenario is run manually, periodically or periodically.

[0022] Furthermore, it also includes: During application construction, the exposure extracts are compiled into a binary string constant table, so that the primitive document produces a consistent set of extracts in any running directory, and consistency checks are set to prevent the string constant table from drifting with the exposure extracts.

[0023] 3) In a third aspect, the present invention also provides a computer device, the computer device including a processor coupled to a memory, the memory storing at least one computer program, the at least one computer program being loaded and executed by the processor to enable the computer device to implement any of the above methods.

[0024] 4) In a fourth aspect, the present invention also provides a computer-readable storage medium storing at least one computer program, which is loaded and executed by a processor to enable a computer to implement any of the above methods.

[0025] It should be noted that the beneficial effects of the technical solutions of the second to fourth aspects of the present invention and their corresponding possible implementations can be found in the above description of the technical effects of the first aspect and its corresponding possible implementations, and will not be repeated here. Attached Figure Description

[0026] Other features, objects, and advantages of the invention will become more apparent from the following detailed description of non-limiting embodiments with reference to the accompanying drawings: Figure 1 This is a flowchart illustrating the steps of a method for synchronizing domain language primitive behaviors with machine-oriented documents, according to an embodiment of the present invention. Figure 2 This is a schematic diagram of the overall architecture of a synchronization method for domain language primitives and machine documents according to an embodiment of the present invention. Figure 3 This is a schematic diagram of the probe behavior flow of a synchronization method for domain language primitive behavior and machine-oriented documents according to an embodiment of the present invention. Figure 4 This is a schematic diagram of the structure of a computer device according to an embodiment of the present invention. Detailed Implementation

[0027] To make the objectives, technical solutions, and advantages of the present invention clearer, the embodiments of the present invention will be described in further detail below with reference to the accompanying drawings.

[0028] like Figure 1 As shown, an embodiment of the present invention provides a method for synchronizing domain language primitive behaviors with machine-oriented documents, the overall architecture of which is as follows: Figure 2As shown: Domain language primitives are linked to the example package, which in turn is linked to the exposed excerpt (corresponding to...). Figure 2 The “exposure tag” in the document projector connects the exposure extract to the document projector, which in turn connects to the machine-oriented primitive document (corresponding to the "exposure tag"). Figure 2 The example package is connected to the "machine-oriented document output" (in this example, the sample package is connected to the validation guard, branch coverage guard, and behavior probe (in this embodiment, the runtime probe scenario). The behavior probe is connected to the flip default guard; the behavior modification of the domain language primitives is connected to the behavior probe. Each primitive usage read by the artificial intelligence through the machine-oriented primitive document channel is rendered by the document projector from the exposure extracts marked by the exposure tags in the example package. The game containing these exposure extracts is triple-checked by the validation guard, branch coverage guard, behavior probe, and flip default guard. The method includes the following steps: S1 constructs an example package for each domain language primitive. The example package includes a runnable instance and a manifest that can be verified by the engine loading process. The runnable instance includes at least one exposed excerpt with an identifier, and the manifest includes a set of identifiers for the runnable instance. The specific implementation is as follows.

[0029] A sample package is built for each domain language primitive. A domain language refers to a declarative configuration language used to describe the game logic in an AI-native game engine. Domain language primitives are the most basic and indivisible building blocks of a domain language; in this embodiment, they specifically include categories such as actions, components, value functions, selectors, and syntactic primitives. These primitives are fixed at compile time and are limited in number, representing the smallest functional unit exposed by the engine to higher-level configurations. A sample package is a collection of a real, minimal, runnable example game and its manifest built for each domain language primitive.

[0030] The sample package consists of two parts: the first part is the runnable game directory, i.e., the runnable instance; the second part is the manifest file, i.e., the manifest. The runnable instance is a real, minimal game that can pass engine loading verification and run. It consists of multiple configuration files, including a Blueprint file (`.bp`), a world manifest file (`.world`), a behavior graph file (`.graph`), and a UI file (`.ui`). The runnable instance is not pseudocode or a fragment, but a complete game that can be judged as error-free by the engine verification tool and can be actually run by the engine testing tool. The manifest is used to declare the metadata of the sample package, including at least primitive categories (actions, components, value functions, selectors, syntax, games, or features, etc.), primitive names, a cover set, and optional fields for whether to have behavior probes and probe reason content fields for skipping probes. The cover set is the list of cover tags, recording all tags exposed by this sample package, and declaring which usage branch tags are exposed in this sample package.

[0031] In the game files of a runnable instance, an exposure excerpt refers to the text content within the runnable instance that is marked by exposure tags and contains fragments of the primitive's own usage. In a preferred embodiment, exposure excerpts are marked by exposure tags, each carrying an identifier; the exposure excerpt contains fragments of the domain language primitive corresponding to the example package; and the identifier corresponds one-to-one with the elements in the identifier set. Specifically, exposure excerpts are marked by embedding pairs of exposure tags in the form of configuration file comments. Each pair of exposure tags consists of a start tag and an end tag. The start tag carries a fixed start symbol, an identifier, and an annotation. The identifier is a stable identifier for the exposure excerpt and corresponds one-to-one with the elements in the identifier set in the manifest; that is, each element in the identifier set corresponds to an exposure excerpt in the runnable instance, and each exposure excerpt in the runnable instance also corresponds to an element in the identifier set. The annotation records the time and purpose of the behavior described by the exposure excerpt. The end tag carries a fixed end symbol. The several behaviors between the start and end tags constitute fragments of the primitive's own usage, i.e., the exposure excerpt. In a runnable instance, all scaffolding code necessary for the game to function, such as blueprints, tags, attributes, and other entities, is placed outside the exposure tags. This ensures that the exposure tags contain only the documented usage of the primitives themselves, guaranteeing that during projection, the exposure excerpts originate from a real, runnable game and focus solely on the primitive's usage without containing irrelevant scaffolding. A primitive's example package can have multiple exposure excerpts, each carrying different identifiers and annotations, demonstrating different branches of the primitive's usage.

[0032] In one alternative, instead of using embedded comments, the exposure tag is declared as a separate bypass list that represents the exposure extract of a primitive from line M to line N of a file in the runnable instance. This bypass list is equivalent to the embedded tag. In another alternative, the extracted text is directly inlined in the list as a structured field and its position in the runnable instance is linked back, with additional consistency checks to prevent drift.

[0033] In a preferred implementation, engine load verification can include: performing engine load verification on a runnable instance during continuous integration, and generating a failure indication when the verification result is not zero errors. The specific implementation is as follows: In a continuous integration pipeline, a validation guard is executed for each sample package. A validation guard is a continuous integration guard that performs engine load validation on the sample package to catch illegal usage drift, such as a parameter being renamed, a syntax being removed, or the mandatory requirement of a parameter being changed. Engine load validation is performed on a runnable instance of each sample package. The engine validation tool performs legality and integrity checks on the runnable instance, specifically including checks on the syntax validity of configuration files, the integrity of references to other resources, parameter validity, and the integrity of the configuration structure. Parameter validity checks cover parameter names, parameter types, parameter mandatory requirements, and the range of enumerated values. In this embodiment, the `ange validate` command is used to perform legality and integrity checks on the runnable instance; `ange validate` is a command name for the engine validation tool. When any validation item is not met, the engine validation tool reports an error, the validation result is not zero errors, the validation guard generates a failure indicator, and the continuous integration build turns red. Only when the validation result is zero errors will the validation guard not generate a failure indicator. The validation guard catches "illegal usage drift": when a parameter is renamed, a syntax is removed, or the mandatory requirement of a parameter changes, the build immediately turns red and generates a failure indicator if the example package is no longer valid. Furthermore, the validation guard requires each example package to contain at least one exposure excerpt; if an empty package exists without any exposure excerpt, a failure indicator is also generated.

[0034] By building a sample package containing a runnable instance and a manifest for each primitive, and using exposure tags to identify exposure excerpts and manifest records to identify sets within the runnable instance, the usage snippets of primitives no longer depend on independently written prose, but are embedded in a real, runnable game. This solves the problem of documentation and implementation being separate sources from each other from the source. Through a validation guard, the runnable instance of the sample package is executed and validated during continuous integration. When an illegal usage change occurs in the primitive implementation, such as parameter renaming, syntax removal, or parameter mandatory changes, the validation guard will capture the invalid sample package and generate a failure indication. This transforms illegal usage drift into a perceptible failure state during the build phase, preventing invalid sample packages from continuing to be used in the documentation projection.

[0035] S2 retrieves all behavior branches of the domain language primitive declarations, examines all behavior branches, and generates a failure indication when any behavior branch does not appear in the identifier set. The specific implementation is as follows.

[0036] For each instance package of action types within a domain language primitive, a branch coverage guard is executed. A branch coverage guard checks whether each behavior branch declared by the primitive has a corresponding exposed extract guard. All behavior branches declared in the implementation of the current domain language primitive are retrieved. Behavior branches refer to different behavior patterns defined by the primitive itself during implementation, specifically including enumerated value branches and pattern branches. For example, a "tracking" action primitive might declare two pattern branches: "continuously track the nearest target every frame" and "lock the first target and stop updating," or multiple enumerated value branches such as "nearest distance mode" and "farthest distance mode."

[0037] Retrieve the set of identifiers from the primitive example package manifest. Check if each behavior branch declared in the primitive has at least one corresponding identifier, and that identifier exists in the identifier set of the manifest. Since each identifier of an exposure extract corresponds one-to-one with an element in the identifier set of the manifest, and each exposure extract demonstrates a specific use of the primitive, when a behavior branch does not have a corresponding identifier, it indicates that the behavior branch is not covered by any exposure extract. If any behavior branch does not appear in the identifier set, the branch coverage guard will turn red if any one of them is missing, generating a failure indication. The branch coverage guard requires that every enumeration value and every pattern branch appear in some exposure extract of the primitive. It is not sufficient to only list common branches; less common branches will not pass the branch coverage guard if they do not appear in the extract. This ensures that the artificial intelligence can understand the true use of each behavior branch of the primitive, rather than just seeing the tip of the iceberg.

[0038] In one alternative, the branch coverage guard requires a one-to-one correspondence between the set of identifiers and the set of branches declared in the primitives; that is, the number of identifiers is exactly equal to the number of branches, and each branch corresponds to exactly one identifier. In another alternative, the branch coverage guard measures branch coverage by runtime arrival rather than textual appearance; that is, each branch is actually reached by at least one probe during execution.

[0039] By mandating that every action branch of the primitive appears in the identifier set, we ensure that each action branch has a corresponding exposure excerpt, thus avoiding the problem that uncommon branches are missed and that artificial intelligence can only guess at branches that are not given examples.

[0040] S3, for example packages configured with probe scenarios, running the probe scenario yields the actual running effect. When an exception occurs while running the probe scenario, a failure indication is generated; otherwise, the described behavior result is determined based on the exposure extract. When the actual running effect does not match the described behavior result, a failure indication is generated. The specific implementation method is as follows.

[0041] like Figure 3As shown in the right-hand branch, for example packages configured with probe scenarios, running the probe scenario verifies whether the behavior described by the exposure extract is consistent with the actual behavior of the primitive. A probe scenario is a test list included with the example package, used to verify the behavior described by the exposure extract through real-world testing.

[0042] In a preferred embodiment, the probe scene operates by: launching a complete engine backend and constructing a game world where physics and events are realistically implemented to achieve a realistic running effect. Specifically, the probe scene operates as follows: This embodiment does not use stubs or dummy instances. Instead, it launches a complete engine backend for each probe scene and constructs a game world where physics and events are realistically implemented. In this game world, physics simulation, collision detection, node updates, and event responses are all realistically implemented; only pixel rendering can be optionally disabled to save resources. A stub is a simplified implementation used to replace a real module, returning a fixed preset value and not executing real logic. A dummy instance (Mock or TestDouble) is a simulated object used to replace a real object, which can be programmed to have specific behaviors and return values. It is used to verify call relationships but does not execute real internal logic. The probe scene runs in this realistically implemented game world, emitting the behavior described in the exposure extract and running for several frames. Subsequently, the probe scene asserts the realistic running effect produced by this behavior on the Entity-Component-System (ECS) architecture. For example, for an exposure excerpt of a "facing" action, the annotation is "make the entity face the nearest enemy every frame." The probe scene will construct a player entity and an enemy entity, construct the real geometry of the player and enemy, let the engine run for several frames, and then assert whether the facing angle of the player entity converges to the real angle calculated from the coordinates of the player entity and the enemy entity. An assertion is an operation that verifies whether a certain condition is true during program execution. If the condition is true, the assertion passes, and the program continues to execute; if the condition is false, the assertion fails, and the program throws an error or returns a failure status. ECS is a data-driven game object architecture, which in this embodiment serves as the runtime state carrier for the probe scene's assertion of the real running effect.

[0043] During the probe scenario's execution, any abnormal situations such as process crashes, timeouts, or empty outputs are considered failures, generating a failure indicator. If the probe scenario completes normal operation, the described behavior result is determined based on the exposure excerpt and its accompanying annotations; that is, the effect that the behavior claimed by the exposure excerpt and its annotations should produce. The actual running effect is compared with the described behavior result. If the two do not match, for example, the player entity's orientation angle does not converge to the expected angle, a failure indicator is generated. If the primitive's semantics change while the exposure excerpt is not synchronized, the probe scenario assertion will inevitably fail, the test turns red, and a failure indicator is generated.

[0044] It is important to emphasize that the assertion targets the actual runtime effect on the ECS architecture after the engine executes the configuration in the exposure excerpt, not the text of the exposure excerpt itself. The exposure excerpt is the input loaded and executed by the engine, i.e., the declarative game configuration; the assertion is an independent verification of the ECS architecture world state generated by this execution. When the underlying implementation of the domain language primitives undergoes semantic changes, such as a modification of default values ​​or a change in the field's writing target, the configuration text in the exposure excerpt remains unchanged and can still be loaded normally by the engine. However, the ECS architecture runtime state generated by its execution will deviate from the expected value asserted by the probe. In this case, the assertion fails, exposing the drift that "the behavior described in the exposure excerpt is no longer the engine's actual behavior." Therefore, the description of the behavioral result comes from the descriptive intent recorded in the exposure excerpt, while the actual runtime effect comes from the actual execution of the engine implementation. The two are only consistent when the engine implementation is faithful to the exposure excerpt.

[0045] In one alternative, for purely visual or purely audio effects, probe scenarios use off-screen frame buffer screenshots plus visual judgments or pixel-by-pixel assertions instead of ECS assertions. In another alternative, multiple probes are run on a single backend startup, sacrificing isolation for speed.

[0046] Since each probe scenario requires launching a complete engine backend (dozens of primitives mean dozens of backend launches, which is time-consuming), in a preferred implementation, running probe scenarios is treated as an independent test unit. This test unit is not incorporated into the rapid unit test suite and is not included in the pre-commit hook. When the behavioral probe corresponding to a probe scenario touches the corresponding domain language primitive behavior or the corresponding example package, the probe scenario is run manually, periodically, or sequentially. Running probe scenarios is treated as a separate, slower test binary, not incorporated into the rapid unit test suite, and not included in the pre-commit hook, but run manually or sequentially when it touches a primitive behavior or its example package. This "slow probe separate" engineering arrangement preserves the authenticity of the overall assertions without hindering daily rapid testing.

[0047] In one alternative, the probe scenario is run in full at scheduled intervals during nightly continuous integration. In another alternative, probes are run incrementally only for the primitives affected by this change.

[0048] It's important to note that a probe scenario is a test checklist included in the sample package. It's static configuration data stored along with the sample package and describes which verifications should be performed on the behaviors described in the exposure excerpt. A behavior probe is a running entity that executes the actual verification actions based on the probe scenario. When a probe scenario is configured in the sample package, the behavior probe is triggered, reading and executing the verification logic defined in the probe scenario, including starting the engine backend, building the realistic game world, issuing behaviors, and performing assertions. The behavior probe can only run if a probe scenario is configured in the sample package; when the behavior probe runs, it performs verifications according to the instructions in the probe scenario.

[0049] By comparing the actual runtime results with the behavioral outcomes described in the excerpt, semantic drift is transformed into a captureable failure indicator, thus solving the problem of silent drift that goes unnoticed when the behavior described in the documentation is inconsistent with the actual implementation of the primitive. Examples of silent drift include: a default value changes its effect, an enumeration value changes its meaning, an action changes the field it's written to, or a value function changes its return value—the usage may still be literal and the branches may still be complete, but the behavior "taught" by the excerpt is now incorrect.

[0050] S4. For example packages without configured probes, determine whether the example package has configured behavior probes. If the example package has configured behavior probes, generate a failure indication when running the behavior probe fails; if the example package does not have configured behavior probes, generate a failure indication when the probe reason content in the list does not meet the preset conditions. The specific implementation method is as follows.

[0051] Perform a default guard flip for each example package. A default guard flip means changing the behavior probe from a default optional guard to a default required guard. If the behavior probe is only optional, semantic drift will still occur silently. Therefore, setting a default guard flip will change it from "no probes by default" to "must probes by default".

[0052] Please continue reading. Figure 3 The example package is obtained for each primitive; it is then determined whether the example package contains a probe scene. If it does, the entire machine engine backend is started and a real game world is constructed, the behavior described in the exposure extract is emitted, and several real frames are run to assert its actual running effect. It is then determined whether the probe scene has run successfully (i.e., the process in S3, and corresponding to...). Figure 3 (As shown in the right-hand branch). Figure 3 As shown in the left branch, if no probe scenario is carried, it is determined whether the list declares no behavior probe and whether it contains specific probe reason content. When the probe reason content in the list does not meet the preset conditions, a failure indication is generated.

[0053] Specifically, it checks whether the example package has a behavior probe configured. If the example package has a behavior probe configured, it runs the behavior probe. If an exception occurs during the execution of the behavior probe, or if the actual execution effect of its assertion does not match the described behavior result, the default conservation is reversed to generate a failure indicator. For example, if a behavior probe is forgotten when adding a new primitive, the construction will fail immediately, generating a failure indicator.

[0054] If the example package does not have a behavior probe configured, check if the probe reason in the manifest meets the preset conditions. The preset conditions include: the manifest must explicitly declare "no behavior probe" and must be accompanied by a specific, non-placeholder reason explaining why the primitive does not have a real operational effect that can be asserted by ECS. If the manifest does not explicitly declare no behavior probe, or the probe reason is empty, or the probe reason is a placeholder such as "to be done," "not applicable," "difficult to test," or "pending," it is determined that it does not meet the preset conditions and a failure indication is generated. Only when the primitive truly has no real operational effect that can be asserted by ECS, such as when the primitive is a purely visual primitive that only modifies rendering geometry and has no real operational effect that can be asserted by ECS other than visual, or a purely audio primitive that only produces audio output and has no real operational effect that can be asserted by ECS, can the manifest be explicitly declared as having no behavior probe and accompanied by a specific probe reason, and the inverted default guard will allow it to pass accordingly. Therefore, the requirement that "every primitive with assertable behavior must have a real behavior probe" becomes an unavoidable hard constraint, which is the final line of defense against the most dangerous drift problem: "the engine behavior changes, the example becomes silent and outdated, and all future generation is taught incorrectly."

[0055] In one alternative, the exception mechanism for the flip default guard does not use a list declaration format, but instead implements a whitelist-based centralized registration of behavior-free probe primitives. These behavior-free probe primitives must be reviewed before being included in the whitelist. In another alternative, the flip default guard defaults to a primitive category: purely visual and purely audio primitives default to behavior-free probes, while other categories default to mandatory behavior probes.

[0056] By flipping the default guard, the behavior probe is changed from optional to mandatory by default. This ensures that every primitive with assertable behavior must be verified by actual execution. Exceptions must be accompanied by specific and non-placeholder reasons, thus systematically guaranteeing that the machine-oriented primitive document is always a verified and executed projection of real behavior.

[0057] S5, when no failure indication is generated, retrieve the exposure extract from the runnable instances based on the identifier set, and render the exposure extract into a machine-oriented primitive document so that the large language model can read the primitive document. The specific implementation is as follows.

[0058] If no failure indications are generated for the verification guard, branch coverage guard, default flip guard, and running probe scenario, document projection is performed. The document projector obtains the set of identifiers from the example package manifest, i.e., the identifier set. Based on each identifier in this identifier set, it searches for the exposure marker carrying the corresponding identifier in the game file of the runnable instance, and parses out the exposure excerpt and its annotations defined by the exposure marker. The document projector assembles all the obtained exposure excerpts along with their annotations into a usage example area in the machine-oriented primitive document, and provides this primitive document to the Large Language Model (LLM) for reading through the product command output channel (e.g., the `angedump` command, the `ange query` command, or the `ange help` command). The Large Language Model (LLM) is an artificial intelligence model that generates configuration data after reading the machine-oriented primitive document. Each primitive usage read by the large language model is a projection of a real, runnable instance that has been marked and extracted through triple checks of verification guards, branch coverage guards, flip default guards, and behavior probes, rather than an independent, handwritten prose. It is impossible to write a separate document for primitives to bypass verification and execution.

[0059] In a preferred embodiment, the method further includes: during application build, incorporating the exposed excerpts into a binary string constant table, ensuring that the primitive document produces a consistent set of excerpts across all running directories, and setting up consistency checks to prevent the string constant table from drifting away from the exposed excerpts. Regardless of whether the application runs from the repository or any directory, the set of excerpts read by the AI ​​is completely consistent, thus eliminating the environment-dependent information loss caused by "silent loss of excerpts depending on the working directory." An additional consistency check ensures that the incorporated string constant table is consistent with the exposed excerpts on disk, preventing them from drifting.

[0060] In one alternative, the document projector reads exposed extracts from a sample directory on disk at runtime, but this sample directory must be distributed along with the binary. In another alternative, the document projector pre-generates separate document data files at build time and distributes them with the package.

[0061] By rendering the exposure excerpt into a primitive document only when no failure indication has been generated by any guards or probes, it ensures that the large language model always reads verified and executed projections of real behavior, fundamentally eliminating the possibility of the large language model reading unverified handwritten documents.

[0062] Example 1: How a single behavioral drift can be captured by a probe as a failure.

[0063] Background: A sample package for a "facing" action contains an exposed annotation stating "make the entity face the nearest enemy every frame." A player and an enemy are constructed within the sample package's probe scene. The engine runs for several frames, asserting that the player's facing angle converges to the true angle calculated from their coordinates (e.g., approximately 135 degrees). Previously, all builds were successful: the validation guard passed, and the branch coverage guard passed. Modification: A developer changed the implementation of the "facing" action, changing the default turning method from "facing the current nearest target every frame" to "locking the first target and not updating." The literal usage, parameters, and branches remained unchanged; the validation guard and branch coverage guard both passed. Without this solution, the sample package's annotation "facing the nearest enemy every frame" becomes a lie. Any AI reading this exposed excerpt would assume the action continuously tracks the nearest enemy, generating incorrect gameplay accordingly. However, in this solution, when the behavior probe binary runs, a complete engine backend is launched for the sample package, running in the real world. Because the player no longer tracks the enemy after it is moved, the player's facing angle no longer converges to the true angle described in the exposed excerpt. The probe assertion fails, generating a failure indicator, and the test turns red. Developers are forced to choose between two options: either roll back the behavior or update both the annotations in the exposed excerpt and the probe assertion to reflect the new behavior. Both paths eliminate the "documentation silently teaching the wrong behavior".

[0064] The method of this invention can be extended to any domain language primitive system that generates configurations after a machine reads a document. It is not limited to game engines. As long as the domain language primitives are finite closed sets, each domain language primitive has a runnable example package, and exposure extraction projection relations, verification guards, branch coverage guards, and flip default guards are applied to the runnable example packages, the synchronization of domain language primitive behavior with machine-oriented documents can be achieved.

[0065] Compared with existing technologies, this invention has the following advantages: While the examples in existing doctest and documentation tests are executed, the runtime environment is a language-level unit or process, not a complete game engine backend that builds a real game world. Therefore, it cannot verify whether the physical, rendering, or event effects produced by running in a real engine match the description. Furthermore, whether doctest passes or fails only guarantees that the example can run, not that the actual behavior of the documented primitives has not changed. If the unit behavior changes but the example still runs, the drift remains silent. Literary programming interweaves code and explanatory text in the same document, but the explanatory prose itself is still handwritten, not executed, and freely driftable, and it does not target the "finite closed set primitives, one runnable example per primitive, branch-by-branch coverage" organization. The component example gallery displays a human-readable visual effect, lacking machine-readable, asserted behavioral contracts. It does not force each behavioral branch to have a story, nor does it have a "missing branch means build failure" guard. Moreover, there is a lack of assertive bridging between the story and the component's actual behavior, so no alarm is triggered when the component behavior changes but the story can still render. Application Programming Interface (API) reference documentation generators extract reference documentation from source code comments. However, the semantic descriptions, examples, and default values ​​in the comment text are still handwritten prose, not executed, not verified, freely drifting, and do not run anything, failing to capture the "inconsistency between the behavior described in the comments and the actual runtime behavior." In this invention, the documentation is not an independent, handwritten true source, but a projection of excerpts from a runnable game; the examples are executed in the real world of the entire machine; behavior branches are forcibly overridden, and failure occurs if a branch is missing; semantic drift is asserted by probes, turning the real ECS effect red and generating a failure indication; the default guard is flipped, forcing each unit to have a probe by default. In terms of verifying realism, this invention starts the entire machine backend and constructs a real game world with each probe, asserting the real ECS effect and stipulating that crashes, timeouts, or empty outputs are all considered failures, thus capturing behavior drift that is only exposed during actual runtime, which existing technologies cannot do. Regarding downstream benefits for machine generation, this invention ensures that the primitive mental model read by artificial intelligence is always a verified and executed projection of real behavior. A document drift is intercepted by guards or probes during the construction phase to prevent contamination of all subsequent generation. Less popular behavior branches are forced to have real excerpts for each branch. The excerpts are what the reader reads and there is no dead data. In contrast, in existing technologies, independent handwritten documents may be outdated and have silent errors, a drift contaminates all generation, less popular branches are often omitted, and examples often become dead data.

[0066] In the above embodiments, although the steps are numbered S1, S2, etc., they are only specific embodiments given by the present invention. Those skilled in the art can adjust the execution order of S1, S2, etc. according to the actual situation, and these situations are also within the protection scope of the present invention. It can be understood that in some embodiments, some or all of the above embodiments may be included.

[0067] Furthermore, the acquisition process of the data involved in this application follows the principles of legality, legitimacy, and necessity. Based on obtaining the explicit authorization and consent of the user, only the minimum necessary information required to achieve the purpose is collected, and data security protection obligations are fulfilled in accordance with the law.

[0068] This invention also provides a synchronization system for domain language primitive behaviors and machine-oriented documents, the specific technical solution of which includes: an example package construction module, a branch coverage guard module, a probe running module, a flip default guard module, and a document projection module; Example package building module is used to build example packages for each domain language primitive. The example package includes a runnable instance and a manifest that can be verified by the engine loading; the runnable instance includes at least one exposed excerpt with an identifier, and the manifest includes a set of identifiers for the runnable instance; The branch coverage guard module is used to obtain all behavior branches of the domain language primitive declaration, check all behavior branches, and generate a failure indication when any behavior branch does not appear in the identifier set. The probe execution module is used to run the probe scenario for example packages configured with probe scenarios to obtain the actual running effect. When an abnormality occurs during the running of the probe scenario, a failure indication is generated; otherwise, the description behavior result is determined based on the exposure extract. When the actual running effect does not match the description behavior result, a failure indication is generated. The default guard module is used to determine whether a sample package has a behavior probe configured for scenarios where no probe is configured. If the sample package has a behavior probe configured, a failure indication is generated when the behavior probe fails to run. If the sample package does not have a behavior probe configured, a failure indication is generated when the probe reason content in the list does not meet the preset conditions. The document projection module is used to obtain exposure extracts from runnable instances based on the identifier set when no failure indications are generated, and render the exposure extracts into machine-oriented primitive documents so that large language models can read the primitive documents.

[0069] It should be noted that the beneficial effects of the domain language primitive behavior and machine document synchronization system provided in the above embodiments are the same as those of the domain language primitive behavior and machine document synchronization method described above, and will not be repeated here. Furthermore, the system provided in the above embodiments is only illustrated by the division of the above functional modules. In practical applications, the above functions can be assigned to different functional modules as needed, that is, the system can be divided into different functional modules according to the actual situation to complete all or part of the functions described above. In addition, the system and method embodiments provided in the above embodiments belong to the same concept, and their specific implementation process is detailed in the method embodiments, and will not be repeated here.

[0070] like Figure 4As shown, an embodiment of the present invention provides a computer device 300, which includes a processor 320 coupled to a memory 310. The memory 310 stores at least one computer program 330, which is loaded and executed by the processor 320 to enable the computer device 300 to implement any of the above-described methods. Specifically: The computer device 300 can vary considerably due to differences in configuration or performance. It may include one or more processors 320 (Central Processing Units, CPUs) and one or more memories 310. The one or more memories 310 store at least one computer program 330, which is loaded and executed by the one or more processors 320 to enable the computer device 300 to implement the domain language primitive behavior and machine-oriented document synchronization method provided in the above embodiments. Of course, the computer device 300 may also have wired or wireless network interfaces, a keyboard, and input / output interfaces for input and output. The computer device 300 may also include other components for implementing device functions, which will not be elaborated here.

[0071] An embodiment of the present invention provides a computer-readable storage medium storing at least one computer program, which is loaded and executed by a processor to enable a computer to implement any of the above-described methods.

[0072] Alternatively, the computer-readable storage medium may be a read-only memory (ROM), a random access memory (RAM), a compact disc read-only memory (CD-ROM), magnetic tape, a floppy disk, and an optical data storage device, etc.

[0073] In an exemplary embodiment, a computer program product or computer program is also provided, comprising computer instructions stored in a computer-readable storage medium. A processor of a computer device reads the computer instructions from the computer-readable storage medium and executes the computer instructions, causing the computer device to perform any of the aforementioned domain-language primitive behaviors and machine-oriented document synchronization methods.

[0074] It should be noted that the terms "first," "second," etc., used in the specification of this application are used to distinguish similar objects and do not imply a specific order or sequence. Where appropriate, the order of use for similar objects can be interchanged so that the embodiments of this application described herein can be implemented in an order other than that shown in the figures or description.

[0075] Those skilled in the art will recognize that this invention can be implemented as a system, method, or computer program product. Therefore, this disclosure can be specifically implemented in the following forms: it can be entirely hardware, entirely software (including firmware, resident software, microcode, etc.), or a combination of hardware and software, generally referred to herein as a "circuit," "module," or "system." Furthermore, in some embodiments, the invention can also be implemented as a computer program product contained in one or more computer-readable media, which includes computer-readable program code.

[0076] Any combination of one or more computer-readable media may be used. A computer-readable medium can be a computer-readable signal medium or a computer-readable storage medium. A computer-readable storage medium can be, for example, but not limited to, an electrical, magnetic, optical, electromagnetic, infrared, or semiconductor system, apparatus, or device, or any combination thereof. More specific examples (a non-exhaustive list) of computer-readable storage media include: an electrical connection having one or more wires, a portable computer disk, a hard disk, random access memory (RAM), read-only memory (ROM), erasable programmable read-only memory (EPROM or flash memory), optical fiber, portable compact disk read-only memory (CD-ROM), optical storage device, magnetic storage device, or any suitable combination thereof. In this document, a computer-readable storage medium can be any tangible medium that contains or stores a program that can be used by or in connection with an instruction execution system, apparatus, or device.

[0077] Although embodiments of the present invention have been shown and described above, it is understood that the above embodiments are exemplary and should not be construed as limiting the present invention. Those skilled in the art can make changes, modifications, substitutions and variations to the above embodiments within the scope of the present invention.

Claims

1. A method for synchronizing domain-specific language primitive behaviors with machine-oriented documents, characterized in that, include: For each domain-specific language primitive, a sample package is built, which includes a runnable instance and manifest that can be verified by the engine loading process; The runnable instance includes at least one exposed excerpt with an identifier, and the manifest includes a set of identifiers for the runnable instance; Obtain all behavior branches of the domain language primitive declaration, check all behavior branches, and generate a failure indication when any behavior branch does not appear in the identifier set; For example packages configured with probe scenarios, the probe scenarios are run to obtain the actual running effect. When an exception occurs while running the probe scenarios, a failure indication is generated; otherwise, the description behavior result is determined based on the exposure extract. When the actual running effect does not match the description behavior result, a failure indication is generated. For example packages in scenarios where no probe is configured, determine whether the example package is configured with a behavior probe. If the example package is configured with the behavior probe, generate a failure indication when running the behavior probe fails. If the example package is not configured with the behavior probe, a failure indication will be generated when the probe reason content in the list does not meet the preset conditions; When no failure indication is generated, an exposure extract is obtained from the runnable instance based on the identifier set, and the exposure extract is rendered into a machine-oriented primitive document so that the large language model can read the primitive document.

2. The method for synchronizing domain language primitive behaviors with machine-oriented documents according to claim 1, characterized in that, The engine loading verification includes: During continuous integration, an engine load check is performed on the runnable instance. If the check result is not zero errors, a failure indication is generated.

3. The method for synchronizing domain language primitive behaviors with machine-oriented documents according to claim 1, characterized in that, The exposure extract is defined by an exposure tag, which carries an identifier; the exposure extract contains usage fragments of the domain language primitives corresponding to the example package; the identifier corresponds one-to-one with the elements in the identifier set.

4. The method for synchronizing domain language primitive behaviors with machine-oriented documents according to claim 1, characterized in that, The operation mode of the probe scene includes: starting a complete engine backend and building a game world where physics and events work realistically in order to obtain the real running effect.

5. The method for synchronizing domain language primitive behaviors with machine-oriented documents according to claim 1, characterized in that, Exceptions that may occur when running the probe scenario include: the process corresponding to the probe scenario crashing, timeout, or empty output; The described behavior outcome is determined by the annotations carried in the exposure extract, which record the time and purpose of the behavior described in the exposure extract.

6. The method for synchronizing domain language primitive behaviors with machine-oriented documents according to claim 1, characterized in that, Also includes: The scenario of running the probe is listed as a separate test unit, which is not incorporated into the rapid unit test suite and is not included in the pre-commit hook; When the behavior probe corresponding to the probe scenario touches the corresponding domain language primitive behavior or touches the corresponding example package, the probe scenario is run manually, periodically, or periodically.

7. The method for synchronizing domain language primitive behaviors with machine-oriented documents according to claim 1, characterized in that, Also includes: During application construction, the exposure extracts are compiled into a binary string constant table, so that the primitive document produces a consistent set of extracts in any running directory, and consistency checks are set to prevent the string constant table from drifting with the exposure extracts.

8. A synchronization system for domain-specific language primitive behaviors and machine-oriented documents, characterized in that, include: Example package building module, branch coverage guard module, probe running module, flip default guard module, and document projection module; The example package building module is used to build an example package for each domain language primitive, and the example package includes a runnable instance and manifest that can be verified by the engine loading. The runnable instance includes at least one exposed excerpt with an identifier, and the manifest includes a set of identifiers for the runnable instance; The branch coverage guard module is used to obtain all behavior branches of the domain language primitive declaration, check all behavior branches, and generate a failure indication when any behavior branch does not appear in the identifier set. The probe running module is used to run the probe scenario for an example package configured with the probe scenario to obtain the actual running effect. When an abnormality occurs when running the probe scenario, a failure indication is generated; otherwise, the description behavior result is determined according to the exposure extract. When the actual running effect does not match the description behavior result, a failure indication is generated. The flip default guard module is used to determine whether the example package is configured with a behavior probe for example packages in scenarios where no probe is configured. If the example package is configured with the behavior probe, a failure indication is generated when the behavior probe fails to run. If the example package is not configured with the behavior probe, a failure indication will be generated when the probe reason content in the list does not meet the preset conditions; The document projection module is used to obtain an exposure extract from the runnable instance based on the identifier set when no failure indication is generated, and render the exposure extract into a machine-oriented primitive document so that the large language model can read the primitive document.

9. A computer device, characterized in that, The computer device includes a processor coupled to a memory storing at least one computer program, which is loaded and executed by the processor to enable the computer device to implement a method for synchronizing domain language primitive behaviors with machine-oriented documents as described in any one of claims 1 to 7.

10. A computer-readable storage medium, characterized in that, The computer-readable storage medium stores at least one computer program, which is loaded and executed by a processor to enable the computer to implement a method for synchronizing domain language primitive behaviors with machine-oriented documents as described in any one of claims 1 to 7.

Images