[
{
"path": ".github/ISSUE_TEMPLATE/ask-question.md",
"content": "---\nname: 提问与交流\nabout: 对框架使用过程中遇到的问题、不清楚或模糊的地方；询问框架能否支持某类需求\n\n---\n\n### 你的问题 | 使用场景\n\n描述你遇到的问题，或使用场景（询问框架能否满足此类需求）\n\n\n\n### 预期值\n\n期望的预期值\n\n\n\n\n### 实际值\n\n实际值\n\n\n\n\n### 复现步骤\n\n描述复现步骤，并提供复现 demo\n\n\n\n\n### 版本\n\n- ioGame version: \n"
},
{
"path": ".github/ISSUE_TEMPLATE/bug-report.md",
"content": "---\nname: bug\nabout: 疑似 bug\n---\n\n### 你的问题\n\n描述你遇到的问题\n\n\n\n### 预期值\n\n期望的预期值\n\n\n\n\n### 实际值\n\n实际值\n\n\n\n### 复现步骤\n\n描述复现步骤，并提供复现 demo\n\n\n\n### 版本\n\n- ioGame version: \n"
},
{
"path": ".github/ISSUE_TEMPLATE/empty-issues.md",
"content": "---\nname: empty issues\nabout: 自定义 issues 描述\n---\n\n### 提问\n\n\n\n\n\n"
},
{
"path": ".github/ISSUE_TEMPLATE/enhance-task.md",
"content": "---\nname: 功能增强建议\nabout: 对框架功能增强、新增...等相关建议\n---\n\n### 新增功能的使用场景\n\n描述功能的使用场景、作用；或描述功能所带来的好处\n\n\n\n"
},
{
"path": ".gitignore",
"content": "### other dir ###\nclasses/\n.temp/\nlogs/\nlog/\n.svn/\nsvn/\nlib/\n.act.*\nsystem/\n\nHELP.md\n!**/src/main/**\n!**/src/test/**\n\n*.class\n\n### jreble config ###\nrebel.xml\n\n### Package Files ###\n*.jar\n*.war\n*.ear\n*.zip\n\n# tcp 与前端通讯的 api\ntcp-api/\n\n# gradle #\nbuild/\n.gradle/\nout/\n\n### maven ###\ntarget/\n!.mvn/wrapper/maven-wrapper.jar\n.mvn\nmvnw\nmvnw.cmd\n### intellj file type ###\nbin/\n.idea\n*.iws\n*.iml\n*.ipr\n\n### NetBeans ###\n/nbproject/private/\n/nbbuild/\n/dist/\n/nbdist/\n/.nb-gradle/\n\n### VS Code ###\n.vscode/\n\n### STS ###\n.apt_generated\n.factorypath\n.settings\n.springBeans\n.sts4-cache\n\n### eclipse file type ###\n.settings/\n.classpath\n.project\n\n### ---- Mac OS X ###\n.DS_Store\nIcon?\n\n### ---- Windows ###\n\n### Windows image file caches ###\nThumbs.db\n\n### Folder integration file ###\nDesktop.ini\n\n### ---- Javadoc ###\ndocs.tar\n\n# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml\nhs_err_pid*\n/target/\n\ndoc_game.txt\n.claude\n"
},
{
"path": "BACKERS.md",
"content": "#### 支持名单\n\n通过 wx、alipay 支付时，不能看见全称，下面使用 '-' 来代替 *。\n\n\n\n#### 2025\n\n##### 小星星\n\n\n| 称号 | 名单 |\n| ---- | ------------------------------------------------ |\n| ⭐⭐ | wuhudsm(admin@playdnf.com)、65714050@qq.com、M-x |\n\n\n\n##### 感谢支持\n\nZhangSir、-鸟\n\n---\n\n\n\n#### 2024\n\n##### 小星星\n\n\n| 称号 | 名单 |\n| ------------- | -------------------------------- |\n| ⭐⭐ | 刘先生、wells974、404 Not Found（342644552）、山里人（higaojun@qq.com ） |\n| ⭐ | 金银花、子在川上（captainl1993@126.com） |\n\n\n\n##### 感谢支持\n\nAlan、Y-g、angelhappyboy、黑天小飞侠\n\n---\n\n\n\n#### 2023\n\n##### 小星星\n\n\n| 称号 | 名单 |\n| ------------- | -------------------------------- |\n| ⭐⭐⭐⭐⭐⭐⭐ | 赵少 |\n| ⭐⭐⭐ | Lei Ante |\n| ⭐⭐ | 张松林、-辉、北极光 |\n| ⭐ | -晖、Bill、明亮北极星 |\n\n\n\n\n##### 感谢支持 \n\nbutxx、玩皮猫、v-v、b-e、M-a、j-s、漫步、森、葱花蛋炒饭、小许\n\n---\n\n\n\n\n#### 2022\n\n##### 小星星\n\n| 称号 | 名单 |\n| ------------- | -------------------------------- |\n| ⭐⭐ | 米斯特姚、WX768925736、猿、Micheal |\n| ⭐ | -称 |\n\n\n\n\n##### 感谢支持 \n\n咖喱、优优、半壁、J-n、华"
},
{
"path": "LICENSE",
"content": " GNU AFFERO GENERAL PUBLIC LICENSE\n Version 3, 19 November 2007\n\n Copyright (C) 2007 Free Software Foundation, Inc. \n Everyone is permitted to copy and distribute verbatim copies\n of this license document, but changing it is not allowed.\n\n Preamble\n\n The GNU Affero General Public License is a free, copyleft license for\nsoftware and other kinds of works, specifically designed to ensure\ncooperation with the community in the case of network server software.\n\n The licenses for most software and other practical works are designed\nto take away your freedom to share and change the works. By contrast,\nour General Public Licenses are intended to guarantee your freedom to\nshare and change all versions of a program--to make sure it remains free\nsoftware for all its users.\n\n When we speak of free software, we are referring to freedom, not\nprice. Our General Public Licenses are designed to make sure that you\nhave the freedom to distribute copies of free software (and charge for\nthem if you wish), that you receive source code or can get it if you\nwant it, that you can change the software or use pieces of it in new\nfree programs, and that you know you can do these things.\n\n Developers that use our General Public Licenses protect your rights\nwith two steps: (1) assert copyright on the software, and (2) offer\nyou this License which gives you legal permission to copy, distribute\nand/or modify the software.\n\n A secondary benefit of defending all users' freedom is that\nimprovements made in alternate versions of the program, if they\nreceive widespread use, become available for other developers to\nincorporate. Many developers of free software are heartened and\nencouraged by the resulting cooperation. However, in the case of\nsoftware used on network servers, this result may fail to come about.\nThe GNU General Public License permits making a modified version and\nletting the public access it on a server without ever releasing its\nsource code to the public.\n\n The GNU Affero General Public License is designed specifically to\nensure that, in such cases, the modified source code becomes available\nto the community. It requires the operator of a network server to\nprovide the source code of the modified version running there to the\nusers of that server. Therefore, public use of a modified version, on\na publicly accessible server, gives the public access to the source\ncode of the modified version.\n\n An older license, called the Affero General Public License and\npublished by Affero, was designed to accomplish similar goals. This is\na different license, not a version of the Affero GPL, but Affero has\nreleased a new version of the Affero GPL which permits relicensing under\nthis license.\n\n The precise terms and conditions for copying, distribution and\nmodification follow.\n\n TERMS AND CONDITIONS\n\n 0. Definitions.\n\n \"This License\" refers to version 3 of the GNU Affero General Public License.\n\n \"Copyright\" also means copyright-like laws that apply to other kinds of\nworks, such as semiconductor masks.\n\n \"The Program\" refers to any copyrightable work licensed under this\nLicense. Each licensee is addressed as \"you\". \"Licensees\" and\n\"recipients\" may be individuals or organizations.\n\n To \"modify\" a work means to copy from or adapt all or part of the work\nin a fashion requiring copyright permission, other than the making of an\nexact copy. The resulting work is called a \"modified version\" of the\nearlier work or a work \"based on\" the earlier work.\n\n A \"covered work\" means either the unmodified Program or a work based\non the Program.\n\n To \"propagate\" a work means to do anything with it that, without\npermission, would make you directly or secondarily liable for\ninfringement under applicable copyright law, except executing it on a\ncomputer or modifying a private copy. Propagation includes copying,\ndistribution (with or without modification), making available to the\npublic, and in some countries other activities as well.\n\n To \"convey\" a work means any kind of propagation that enables other\nparties to make or receive copies. Mere interaction with a user through\na computer network, with no transfer of a copy, is not conveying.\n\n An interactive user interface displays \"Appropriate Legal Notices\"\nto the extent that it includes a convenient and prominently visible\nfeature that (1) displays an appropriate copyright notice, and (2)\ntells the user that there is no warranty for the work (except to the\nextent that warranties are provided), that licensees may convey the\nwork under this License, and how to view a copy of this License. If\nthe interface presents a list of user commands or options, such as a\nmenu, a prominent item in the list meets this criterion.\n\n 1. Source Code.\n\n The \"source code\" for a work means the preferred form of the work\nfor making modifications to it. \"Object code\" means any non-source\nform of a work.\n\n A \"Standard Interface\" means an interface that either is an official\nstandard defined by a recognized standards body, or, in the case of\ninterfaces specified for a particular programming language, one that\nis widely used among developers working in that language.\n\n The \"System Libraries\" of an executable work include anything, other\nthan the work as a whole, that (a) is included in the normal form of\npackaging a Major Component, but which is not part of that Major\nComponent, and (b) serves only to enable use of the work with that\nMajor Component, or to implement a Standard Interface for which an\nimplementation is available to the public in source code form. A\n\"Major Component\", in this context, means a major essential component\n(kernel, window system, and so on) of the specific operating system\n(if any) on which the executable work runs, or a compiler used to\nproduce the work, or an object code interpreter used to run it.\n\n The \"Corresponding Source\" for a work in object code form means all\nthe source code needed to generate, install, and (for an executable\nwork) run the object code and to modify the work, including scripts to\ncontrol those activities. However, it does not include the work's\nSystem Libraries, or general-purpose tools or generally available free\nprograms which are used unmodified in performing those activities but\nwhich are not part of the work. For example, Corresponding Source\nincludes interface definition files associated with source files for\nthe work, and the source code for shared libraries and dynamically\nlinked subprograms that the work is specifically designed to require,\nsuch as by intimate data communication or control flow between those\nsubprograms and other parts of the work.\n\n The Corresponding Source need not include anything that users\ncan regenerate automatically from other parts of the Corresponding\nSource.\n\n The Corresponding Source for a work in source code form is that\nsame work.\n\n 2. Basic Permissions.\n\n All rights granted under this License are granted for the term of\ncopyright on the Program, and are irrevocable provided the stated\nconditions are met. This License explicitly affirms your unlimited\npermission to run the unmodified Program. The output from running a\ncovered work is covered by this License only if the output, given its\ncontent, constitutes a covered work. This License acknowledges your\nrights of fair use or other equivalent, as provided by copyright law.\n\n You may make, run and propagate covered works that you do not\nconvey, without conditions so long as your license otherwise remains\nin force. You may convey covered works to others for the sole purpose\nof having them make modifications exclusively for you, or provide you\nwith facilities for running those works, provided that you comply with\nthe terms of this License in conveying all material for which you do\nnot control copyright. Those thus making or running the covered works\nfor you must do so exclusively on your behalf, under your direction\nand control, on terms that prohibit them from making any copies of\nyour copyrighted material outside their relationship with you.\n\n Conveying under any other circumstances is permitted solely under\nthe conditions stated below. Sublicensing is not allowed; section 10\nmakes it unnecessary.\n\n 3. Protecting Users' Legal Rights From Anti-Circumvention Law.\n\n No covered work shall be deemed part of an effective technological\nmeasure under any applicable law fulfilling obligations under article\n11 of the WIPO copyright treaty adopted on 20 December 1996, or\nsimilar laws prohibiting or restricting circumvention of such\nmeasures.\n\n When you convey a covered work, you waive any legal power to forbid\ncircumvention of technological measures to the extent such circumvention\nis effected by exercising rights under this License with respect to\nthe covered work, and you disclaim any intention to limit operation or\nmodification of the work as a means of enforcing, against the work's\nusers, your or third parties' legal rights to forbid circumvention of\ntechnological measures.\n\n 4. Conveying Verbatim Copies.\n\n You may convey verbatim copies of the Program's source code as you\nreceive it, in any medium, provided that you conspicuously and\nappropriately publish on each copy an appropriate copyright notice;\nkeep intact all notices stating that this License and any\nnon-permissive terms added in accord with section 7 apply to the code;\nkeep intact all notices of the absence of any warranty; and give all\nrecipients a copy of this License along with the Program.\n\n You may charge any price or no price for each copy that you convey,\nand you may offer support or warranty protection for a fee.\n\n 5. Conveying Modified Source Versions.\n\n You may convey a work based on the Program, or the modifications to\nproduce it from the Program, in the form of source code under the\nterms of section 4, provided that you also meet all of these conditions:\n\n a) The work must carry prominent notices stating that you modified\n it, and giving a relevant date.\n\n b) The work must carry prominent notices stating that it is\n released under this License and any conditions added under section\n 7. This requirement modifies the requirement in section 4 to\n \"keep intact all notices\".\n\n c) You must license the entire work, as a whole, under this\n License to anyone who comes into possession of a copy. This\n License will therefore apply, along with any applicable section 7\n additional terms, to the whole of the work, and all its parts,\n regardless of how they are packaged. This License gives no\n permission to license the work in any other way, but it does not\n invalidate such permission if you have separately received it.\n\n d) If the work has interactive user interfaces, each must display\n Appropriate Legal Notices; however, if the Program has interactive\n interfaces that do not display Appropriate Legal Notices, your\n work need not make them do so.\n\n A compilation of a covered work with other separate and independent\nworks, which are not by their nature extensions of the covered work,\nand which are not combined with it such as to form a larger program,\nin or on a volume of a storage or distribution medium, is called an\n\"aggregate\" if the compilation and its resulting copyright are not\nused to limit the access or legal rights of the compilation's users\nbeyond what the individual works permit. Inclusion of a covered work\nin an aggregate does not cause this License to apply to the other\nparts of the aggregate.\n\n 6. Conveying Non-Source Forms.\n\n You may convey a covered work in object code form under the terms\nof sections 4 and 5, provided that you also convey the\nmachine-readable Corresponding Source under the terms of this License,\nin one of these ways:\n\n a) Convey the object code in, or embodied in, a physical product\n (including a physical distribution medium), accompanied by the\n Corresponding Source fixed on a durable physical medium\n customarily used for software interchange.\n\n b) Convey the object code in, or embodied in, a physical product\n (including a physical distribution medium), accompanied by a\n written offer, valid for at least three years and valid for as\n long as you offer spare parts or customer support for that product\n model, to give anyone who possesses the object code either (1) a\n copy of the Corresponding Source for all the software in the\n product that is covered by this License, on a durable physical\n medium customarily used for software interchange, for a price no\n more than your reasonable cost of physically performing this\n conveying of source, or (2) access to copy the\n Corresponding Source from a network server at no charge.\n\n c) Convey individual copies of the object code with a copy of the\n written offer to provide the Corresponding Source. This\n alternative is allowed only occasionally and noncommercially, and\n only if you received the object code with such an offer, in accord\n with subsection 6b.\n\n d) Convey the object code by offering access from a designated\n place (gratis or for a charge), and offer equivalent access to the\n Corresponding Source in the same way through the same place at no\n further charge. You need not require recipients to copy the\n Corresponding Source along with the object code. If the place to\n copy the object code is a network server, the Corresponding Source\n may be on a different server (operated by you or a third party)\n that supports equivalent copying facilities, provided you maintain\n clear directions next to the object code saying where to find the\n Corresponding Source. Regardless of what server hosts the\n Corresponding Source, you remain obligated to ensure that it is\n available for as long as needed to satisfy these requirements.\n\n e) Convey the object code using peer-to-peer transmission, provided\n you inform other peers where the object code and Corresponding\n Source of the work are being offered to the general public at no\n charge under subsection 6d.\n\n A separable portion of the object code, whose source code is excluded\nfrom the Corresponding Source as a System Library, need not be\nincluded in conveying the object code work.\n\n A \"User Product\" is either (1) a \"consumer product\", which means any\ntangible personal property which is normally used for personal, family,\nor household purposes, or (2) anything designed or sold for incorporation\ninto a dwelling. In determining whether a product is a consumer product,\ndoubtful cases shall be resolved in favor of coverage. For a particular\nproduct received by a particular user, \"normally used\" refers to a\ntypical or common use of that class of product, regardless of the status\nof the particular user or of the way in which the particular user\nactually uses, or expects or is expected to use, the product. A product\nis a consumer product regardless of whether the product has substantial\ncommercial, industrial or non-consumer uses, unless such uses represent\nthe only significant mode of use of the product.\n\n \"Installation Information\" for a User Product means any methods,\nprocedures, authorization keys, or other information required to install\nand execute modified versions of a covered work in that User Product from\na modified version of its Corresponding Source. The information must\nsuffice to ensure that the continued functioning of the modified object\ncode is in no case prevented or interfered with solely because\nmodification has been made.\n\n If you convey an object code work under this section in, or with, or\nspecifically for use in, a User Product, and the conveying occurs as\npart of a transaction in which the right of possession and use of the\nUser Product is transferred to the recipient in perpetuity or for a\nfixed term (regardless of how the transaction is characterized), the\nCorresponding Source conveyed under this section must be accompanied\nby the Installation Information. But this requirement does not apply\nif neither you nor any third party retains the ability to install\nmodified object code on the User Product (for example, the work has\nbeen installed in ROM).\n\n The requirement to provide Installation Information does not include a\nrequirement to continue to provide support service, warranty, or updates\nfor a work that has been modified or installed by the recipient, or for\nthe User Product in which it has been modified or installed. Access to a\nnetwork may be denied when the modification itself materially and\nadversely affects the operation of the network or violates the rules and\nprotocols for communication across the network.\n\n Corresponding Source conveyed, and Installation Information provided,\nin accord with this section must be in a format that is publicly\ndocumented (and with an implementation available to the public in\nsource code form), and must require no special password or key for\nunpacking, reading or copying.\n\n 7. Additional Terms.\n\n \"Additional permissions\" are terms that supplement the terms of this\nLicense by making exceptions from one or more of its conditions.\nAdditional permissions that are applicable to the entire Program shall\nbe treated as though they were included in this License, to the extent\nthat they are valid under applicable law. If additional permissions\napply only to part of the Program, that part may be used separately\nunder those permissions, but the entire Program remains governed by\nthis License without regard to the additional permissions.\n\n When you convey a copy of a covered work, you may at your option\nremove any additional permissions from that copy, or from any part of\nit. (Additional permissions may be written to require their own\nremoval in certain cases when you modify the work.) You may place\nadditional permissions on material, added by you to a covered work,\nfor which you have or can give appropriate copyright permission.\n\n Notwithstanding any other provision of this License, for material you\nadd to a covered work, you may (if authorized by the copyright holders of\nthat material) supplement the terms of this License with terms:\n\n a) Disclaiming warranty or limiting liability differently from the\n terms of sections 15 and 16 of this License; or\n\n b) Requiring preservation of specified reasonable legal notices or\n author attributions in that material or in the Appropriate Legal\n Notices displayed by works containing it; or\n\n c) Prohibiting misrepresentation of the origin of that material, or\n requiring that modified versions of such material be marked in\n reasonable ways as different from the original version; or\n\n d) Limiting the use for publicity purposes of names of licensors or\n authors of the material; or\n\n e) Declining to grant rights under trademark law for use of some\n trade names, trademarks, or service marks; or\n\n f) Requiring indemnification of licensors and authors of that\n material by anyone who conveys the material (or modified versions of\n it) with contractual assumptions of liability to the recipient, for\n any liability that these contractual assumptions directly impose on\n those licensors and authors.\n\n All other non-permissive additional terms are considered \"further\nrestrictions\" within the meaning of section 10. If the Program as you\nreceived it, or any part of it, contains a notice stating that it is\ngoverned by this License along with a term that is a further\nrestriction, you may remove that term. If a license document contains\na further restriction but permits relicensing or conveying under this\nLicense, you may add to a covered work material governed by the terms\nof that license document, provided that the further restriction does\nnot survive such relicensing or conveying.\n\n If you add terms to a covered work in accord with this section, you\nmust place, in the relevant source files, a statement of the\nadditional terms that apply to those files, or a notice indicating\nwhere to find the applicable terms.\n\n Additional terms, permissive or non-permissive, may be stated in the\nform of a separately written license, or stated as exceptions;\nthe above requirements apply either way.\n\n 8. Termination.\n\n You may not propagate or modify a covered work except as expressly\nprovided under this License. Any attempt otherwise to propagate or\nmodify it is void, and will automatically terminate your rights under\nthis License (including any patent licenses granted under the third\nparagraph of section 11).\n\n However, if you cease all violation of this License, then your\nlicense from a particular copyright holder is reinstated (a)\nprovisionally, unless and until the copyright holder explicitly and\nfinally terminates your license, and (b) permanently, if the copyright\nholder fails to notify you of the violation by some reasonable means\nprior to 60 days after the cessation.\n\n Moreover, your license from a particular copyright holder is\nreinstated permanently if the copyright holder notifies you of the\nviolation by some reasonable means, this is the first time you have\nreceived notice of violation of this License (for any work) from that\ncopyright holder, and you cure the violation prior to 30 days after\nyour receipt of the notice.\n\n Termination of your rights under this section does not terminate the\nlicenses of parties who have received copies or rights from you under\nthis License. If your rights have been terminated and not permanently\nreinstated, you do not qualify to receive new licenses for the same\nmaterial under section 10.\n\n 9. Acceptance Not Required for Having Copies.\n\n You are not required to accept this License in order to receive or\nrun a copy of the Program. Ancillary propagation of a covered work\noccurring solely as a consequence of using peer-to-peer transmission\nto receive a copy likewise does not require acceptance. However,\nnothing other than this License grants you permission to propagate or\nmodify any covered work. These actions infringe copyright if you do\nnot accept this License. Therefore, by modifying or propagating a\ncovered work, you indicate your acceptance of this License to do so.\n\n 10. Automatic Licensing of Downstream Recipients.\n\n Each time you convey a covered work, the recipient automatically\nreceives a license from the original licensors, to run, modify and\npropagate that work, subject to this License. You are not responsible\nfor enforcing compliance by third parties with this License.\n\n An \"entity transaction\" is a transaction transferring control of an\norganization, or substantially all assets of one, or subdividing an\norganization, or merging organizations. If propagation of a covered\nwork results from an entity transaction, each party to that\ntransaction who receives a copy of the work also receives whatever\nlicenses to the work the party's predecessor in interest had or could\ngive under the previous paragraph, plus a right to possession of the\nCorresponding Source of the work from the predecessor in interest, if\nthe predecessor has it or can get it with reasonable efforts.\n\n You may not impose any further restrictions on the exercise of the\nrights granted or affirmed under this License. For example, you may\nnot impose a license fee, royalty, or other charge for exercise of\nrights granted under this License, and you may not initiate litigation\n(including a cross-claim or counterclaim in a lawsuit) alleging that\nany patent claim is infringed by making, using, selling, offering for\nsale, or importing the Program or any portion of it.\n\n 11. Patents.\n\n A \"contributor\" is a copyright holder who authorizes use under this\nLicense of the Program or a work on which the Program is based. The\nwork thus licensed is called the contributor's \"contributor version\".\n\n A contributor's \"essential patent claims\" are all patent claims\nowned or controlled by the contributor, whether already acquired or\nhereafter acquired, that would be infringed by some manner, permitted\nby this License, of making, using, or selling its contributor version,\nbut do not include claims that would be infringed only as a\nconsequence of further modification of the contributor version. For\npurposes of this definition, \"control\" includes the right to grant\npatent sublicenses in a manner consistent with the requirements of\nthis License.\n\n Each contributor grants you a non-exclusive, worldwide, royalty-free\npatent license under the contributor's essential patent claims, to\nmake, use, sell, offer for sale, import and otherwise run, modify and\npropagate the contents of its contributor version.\n\n In the following three paragraphs, a \"patent license\" is any express\nagreement or commitment, however denominated, not to enforce a patent\n(such as an express permission to practice a patent or covenant not to\nsue for patent infringement). To \"grant\" such a patent license to a\nparty means to make such an agreement or commitment not to enforce a\npatent against the party.\n\n If you convey a covered work, knowingly relying on a patent license,\nand the Corresponding Source of the work is not available for anyone\nto copy, free of charge and under the terms of this License, through a\npublicly available network server or other readily accessible means,\nthen you must either (1) cause the Corresponding Source to be so\navailable, or (2) arrange to deprive yourself of the benefit of the\npatent license for this particular work, or (3) arrange, in a manner\nconsistent with the requirements of this License, to extend the patent\nlicense to downstream recipients. \"Knowingly relying\" means you have\nactual knowledge that, but for the patent license, your conveying the\ncovered work in a country, or your recipient's use of the covered work\nin a country, would infringe one or more identifiable patents in that\ncountry that you have reason to believe are valid.\n\n If, pursuant to or in connection with a single transaction or\narrangement, you convey, or propagate by procuring conveyance of, a\ncovered work, and grant a patent license to some of the parties\nreceiving the covered work authorizing them to use, propagate, modify\nor convey a specific copy of the covered work, then the patent license\nyou grant is automatically extended to all recipients of the covered\nwork and works based on it.\n\n A patent license is \"discriminatory\" if it does not include within\nthe scope of its coverage, prohibits the exercise of, or is\nconditioned on the non-exercise of one or more of the rights that are\nspecifically granted under this License. You may not convey a covered\nwork if you are a party to an arrangement with a third party that is\nin the business of distributing software, under which you make payment\nto the third party based on the extent of your activity of conveying\nthe work, and under which the third party grants, to any of the\nparties who would receive the covered work from you, a discriminatory\npatent license (a) in connection with copies of the covered work\nconveyed by you (or copies made from those copies), or (b) primarily\nfor and in connection with specific products or compilations that\ncontain the covered work, unless you entered into that arrangement,\nor that patent license was granted, prior to 28 March 2007.\n\n Nothing in this License shall be construed as excluding or limiting\nany implied license or other defenses to infringement that may\notherwise be available to you under applicable patent law.\n\n 12. No Surrender of Others' Freedom.\n\n If conditions are imposed on you (whether by court order, agreement or\notherwise) that contradict the conditions of this License, they do not\nexcuse you from the conditions of this License. If you cannot convey a\ncovered work so as to satisfy simultaneously your obligations under this\nLicense and any other pertinent obligations, then as a consequence you may\nnot convey it at all. For example, if you agree to terms that obligate you\nto collect a royalty for further conveying from those to whom you convey\nthe Program, the only way you could satisfy both those terms and this\nLicense would be to refrain entirely from conveying the Program.\n\n 13. Remote Network Interaction; Use with the GNU General Public License.\n\n Notwithstanding any other provision of this License, if you modify the\nProgram, your modified version must prominently offer all users\ninteracting with it remotely through a computer network (if your version\nsupports such interaction) an opportunity to receive the Corresponding\nSource of your version by providing access to the Corresponding Source\nfrom a network server at no charge, through some standard or customary\nmeans of facilitating copying of software. This Corresponding Source\nshall include the Corresponding Source for any work covered by version 3\nof the GNU General Public License that is incorporated pursuant to the\nfollowing paragraph.\n\n Notwithstanding any other provision of this License, you have\npermission to link or combine any covered work with a work licensed\nunder version 3 of the GNU General Public License into a single\ncombined work, and to convey the resulting work. The terms of this\nLicense will continue to apply to the part which is the covered work,\nbut the work with which it is combined will remain governed by version\n3 of the GNU General Public License.\n\n 14. Revised Versions of this License.\n\n The Free Software Foundation may publish revised and/or new versions of\nthe GNU Affero General Public License from time to time. Such new versions\nwill be similar in spirit to the present version, but may differ in detail to\naddress new problems or concerns.\n\n Each version is given a distinguishing version number. If the\nProgram specifies that a certain numbered version of the GNU Affero General\nPublic License \"or any later version\" applies to it, you have the\noption of following the terms and conditions either of that numbered\nversion or of any later version published by the Free Software\nFoundation. If the Program does not specify a version number of the\nGNU Affero General Public License, you may choose any version ever published\nby the Free Software Foundation.\n\n If the Program specifies that a proxy can decide which future\nversions of the GNU Affero General Public License can be used, that proxy's\npublic statement of acceptance of a version permanently authorizes you\nto choose that version for the Program.\n\n Later license versions may give you additional or different\npermissions. However, no additional obligations are imposed on any\nauthor or copyright holder as a result of your choosing to follow a\nlater version.\n\n 15. Disclaimer of Warranty.\n\n THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY\nAPPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT\nHOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM \"AS IS\" WITHOUT WARRANTY\nOF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,\nTHE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR\nPURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM\nIS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF\nALL NECESSARY SERVICING, REPAIR OR CORRECTION.\n\n 16. Limitation of Liability.\n\n IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING\nWILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS\nTHE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY\nGENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE\nUSE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF\nDATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD\nPARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),\nEVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF\nSUCH DAMAGES.\n\n 17. Interpretation of Sections 15 and 16.\n\n If the disclaimer of warranty and limitation of liability provided\nabove cannot be given local legal effect according to their terms,\nreviewing courts shall apply local law that most closely approximates\nan absolute waiver of all civil liability in connection with the\nProgram, unless a warranty or assumption of liability accompanies a\ncopy of the Program in return for a fee.\n\n END OF TERMS AND CONDITIONS\n\n How to Apply These Terms to Your New Programs\n\n If you develop a new program, and you want it to be of the greatest\npossible use to the public, the best way to achieve this is to make it\nfree software which everyone can redistribute and change under these terms.\n\n To do so, attach the following notices to the program. It is safest\nto attach them to the start of each source file to most effectively\nstate the exclusion of warranty; and each file should have at least\nthe \"copyright\" line and a pointer to where the full notice is found.\n\n \n Copyright (C) \n\n This program is free software: you can redistribute it and/or modify\n it under the terms of the GNU Affero General Public License as published by\n the Free Software Foundation, either version 3 of the License, or\n (at your option) any later version.\n\n This program is distributed in the hope that it will be useful,\n but WITHOUT ANY WARRANTY; without even the implied warranty of\n MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n GNU Affero General Public License for more details.\n\n You should have received a copy of the GNU Affero General Public License\n along with this program. If not, see .\n\nAlso add information on how to contact you by electronic and paper mail.\n\n If your software can interact with users remotely through a computer\nnetwork, you should also make sure that it provides a way for users to\nget its source. For example, if your program is a web application, its\ninterface could display a \"Source\" link that leads users to an archive\nof the code. There are many ways you could offer source, and different\nsolutions will be better for different programs; see section 13 for the\nspecific requirements.\n\n You should also get your employer (if you work as a programmer) or school,\nif any, to sign a \"copyright disclaimer\" for the program, if necessary.\nFor more information on this, and how to apply and follow the GNU AGPL, see\n.\n"
},
{
"path": "README.md",
"content": "
\n ioGame\n
\n
\n Lock-free, async, event-driven architecture — supports clustering & distribution out of the box, no middleware required\n \n Build decentralized, auto-scaling, multi-process distributed game servers with ease\n \n Tiny footprint, blazing-fast startup, low memory usage, zero config files, elegant route-level access control\n \n Simultaneous support for WebSocket, UDP, TCP and more — with built-in full-link distributed tracing\n \n One codebase, multiple protocols — seamlessly switch between Protobuf, JSON, and beyond\n \n Near-native performance — 11.52 million business operations per second in a single thread\n \n Code-as-documentation, JSR380 validation, assertion + exception patterns — minimal maintenance overhead\n \n Smart same-process affinity with IDE-friendly code navigation & jump-to-source\n \n Deploy your way — components run independently or fused together\n \n Write once, generate client SDKs — interactive code generation for any frontend\n \n Cross-process, cross-machine communication between logic servers\n \n Dynamic player-to-server binding\n \n Plays nicely with any framework\n \n Feels natural for web MVC developers\n \n No hard dependency on Spring\n \n Zero learning curve\n \n Pure JavaSE\n
\n\n\nDocumentation: https://iohao.github.io/game/docs/intro\n\n## Vision\nMake game server development effortless. We're here to change the industry — lowering the barrier to entry and making game development tools truly accessible to everyone.\n\n\n## Open, Free & Developer-Friendly License\n- There is no commercial edition — never has been, never will be. Every feature is open source.\n- We're committed to at least **ten years** of active maintenance, starting from 2022-03-01.\n- ioGame is a lightweight networking framework built for **online games, IoT, internal systems**, and any scenario that needs persistent connections. The source code is fully open, documentation is free, and usage costs nothing (subject to license terms).\n\n\n\n**Why AGPL 3.0?**\n\nioGame is released under the [AGPL 3.0](https://www.gnu.org/licenses/agpl-3.0.txt) license. Projects built with ioGame under this license are free of charge.\n\nWe chose AGPL 3.0 because it's **fairer to developers**. It ensures that project ownership is shared — meaning that even if a developer leaves a company, they retain legitimate rights to the project they helped build.\n\nContrast this with permissive licenses like Apache 2.0 or MIT, where developers who leave a company lose all control over the project and get nothing in return. We've all seen it: developers pour their hearts into a project through countless late nights and weekends, only to be let go right before — or just after — launch, watching their hard work become someone else's asset.\n\nUnder AGPL 3.0, shared ownership means developers are genuinely motivated to invest in and polish their work.\n\n\n\n## Startup Showcase\n\nioGame is impressively lean:\n- **Memory**: Minimal footprint.\n- **Startup**: Applications typically boot in under **1 second**.\n- **Package size**: ~**15 MB** as a jar.\n\n\n\n\n\n## What is ioGame?\n\nLooking for a game server framework that's **high-performance, stable, easy to use, with built-in load balancing, clean architecture (no class explosion), cross-process communication, decentralized clustering, auto-scaling, and stateful multi-process distribution**? Meet ioGame — a Java networking framework designed exactly for this.\n\n\n\nioGame is a lightweight networking framework built for **online games, IoT, internal systems**, and any scenario that needs persistent connections.\n\n\n\n**Key Features at a Glance:**\n\n> 1. Truly lightweight — lock-free, async, event-driven from the ground up.\n> 2. Small package, low memory, fast startup.\n> 3. Pure JavaSE — integrates effortlessly with Spring, Vert.x, Quarkus, Solon, and others.\n> 4. **Zero learning curve.** If you know basic Java or web MVC, you already know how to use ioGame. No game dev experience required.\n> 5. Architecturally eliminates the **N×N scaling problem** that plagues traditional frameworks.\n> 6. **No third-party dependencies** for clustering & distribution — just a JVM is all you need.\n> 7. Three-part architecture: External Server + Broker (Gateway) + Game Logic Server — each can run **independently or fused together**, adapting to **any game type**.\n> 8. Fully **dynamic scaling** — add or remove External Servers, Logic Servers, and Brokers on the fly.\n> 9. **Multi-server, single-process** mode for development — debug distributed systems as easily as a monolith.\n> 10. Logic Servers can run standalone, **enabling true modularization**.\n> 11. Built-in **full-link distributed tracing**.\n> 12. Rich communication primitives — logic servers can talk across machines seamlessly.\n> 13. MVC-style coding with non-intrusive Java Beans — effectively **prevents class explosion**.\n> 14. Built-in **per-player thread safety** — concurrency handled for you.\n> 15. **One codebase** supports TCP, WebSocket, UDP simultaneously — no code changes needed. Extensible to KCP, QUIC, and beyond.\n> 16. **One codebase** for switching data protocols — Protobuf, JSON, and more. Extensible.\n> 17. **Hot-swap protocols** — add or remove protocols without restarting the gateway or External Server. No player disconnections.\n> 18. Auto-boxing/unboxing of primitives in actions — solves the [protocol fragment](https://iohao.github.io/game/docs/manual/protocol_fragment) problem.\n> 19. Pluggable, extensible **plugin system**.\n> 20. Deploy as **single-process** or **multi-process across machines** — switch freely without code changes.\n> 21. Logic Servers never expose ports — **immune to port-scanning attacks** by design.\n> 22. Built-in **stress testing & simulation module** with real network conditions, continuous interaction, and automation support.\n> 23. Sync, async, and async-callback methods for inter-service communication.\n> 24. **Distributed event bus** (like MQ / Redis pub-sub — works across machines and processes).\n> 25. Elegant **route-level access control**.\n> 26. Intelligent **same-process affinity**.\n> 27. JSR380 validation + assertions + exceptions = **less boilerplate, fewer bugs**.\n> 28. **Write once, generate everywhere** — produce unified interactive SDKs for Godot, UE, Unity, Cocos Creator, Laya, React, Vue, Angular, and more. Massive productivity boost.\n\n\n\nPackaging, memory, and startup are all best-in-class: jar size ~**15 MB**, startup typically under **1 second**, low memory footprint.\n\n\n\n**Ecosystem integration** is straightforward — [Spring integration](https://iohao.github.io/game/docs/manual/integration_spring) takes just 4 lines of code. Beyond Spring, ioGame plays well with Vert.x, Quarkus, Solon, and any other framework, letting you tap into their ecosystems.\n\n\n\n**Zero learning curve.** If you know basic Java or web MVC patterns, you're ready. No game development background needed.\n\n\n\n**Clean coding style.** ioGame provides MVC-like conventions with non-intrusive Java Beans, effectively **preventing class explosion**. Sync, async, and callback methods are available for inter-service calls — resulting in elegant code with full-link tracing baked in.\n\n\n\n**Write once, connect everywhere.** ioGame generates client interaction code automatically, dramatically cutting client-side workload. Write your Java code once and generate unified SDKs for [Godot](https://godotengine.org/), [UE](https://www.unrealengine.com/), [Unity](https://unity.com/), [Cocos Creator](https://www.cocos.com/), [Laya](https://layaair.layabox.com/#/), [React](https://react.dev/), [Vue](https://vuejs.org/), [Angular](https://angular.dev/), and more. Supports [code generation](https://iohao.github.io/game/docs/examples/code_generate) in C#, TypeScript, GDScript, and C++ — fully extensible.\n\n\n\n**No N×N headaches.** Traditional architectures rely on Redis, MQ, ZooKeeper, and other middleware to scale — hardly \"lightweight.\" ioGame solves the [N×N problem](https://iohao.github.io/game/docs/overall/legacy_system) architecturally, without external dependencies.\n\n\n\n**Truly lightweight.** No third-party middleware or database is needed for clustering and distribution — just a JVM. This simplifies usage and slashes deployment and maintenance costs. A single dependency gives you the entire framework — no Nginx, Redis, MQ, MySQL, ZooKeeper, or Protobuf compiler to install.\n\n\n\n**Flexible architecture.** ioGame's [three-part design](https://iohao.github.io/game/docs/overall/deploy_flexible) — External Server, Broker (Gateway), Game Logic Server — can run independently or merged together, adapting to **any game type** simply by adjusting deployment. These changes are trivial and never break existing code.\n\n\n\n**Dynamic scaling.** External Servers, Logic Servers, and Brokers all support live addition and removal. Scale up or down as player counts change. The architecture also enables **zero-downtime updates**: spin up new servers (A-3, A-4) with your latest features, then gracefully retire the old ones (A-1, A-2) — players never notice.\n\n\n\n**Decentralized clustering.** The Broker (Gateway) uses a [masterless, self-organizing cluster design](https://iohao.github.io/game/docs/examples/server/example_broker_cluster) — all nodes are equal and autonomous with no single point of failure. The cluster **auto-manages and elastically scales**, maintaining load balance and consistency as nodes join or leave.\n\n\n\n**Distributed by design.** Logic servers are organized into distinct layers — [External Servers](https://iohao.github.io/game/docs/overall/external_intro), [Game Logic Servers](https://iohao.github.io/game/docs/overall/logic_intro) — each with clear responsibilities and interfaces. This improves readability, maintainability, and enables effortless **horizontal scaling**.\n\n\n\n**Developer-friendly distributed development.** Distributed apps usually mean juggling multiple processes, making debugging painful. Most frameworks can't solve this — **ioGame can.** Multi-server single-process mode lets you develop and debug distributed systems as if they were monoliths.\n\n\n\n**Modular ecosystem.** [Game Logic Servers can run standalone](https://iohao.github.io/game/docs/manual_high/your_ecology) — just plug into the Broker to provide services. Build reusable, **componentized logic servers** — Guild, Friends, Login, Lottery, Announcements, Leaderboards, and more. Benefits include:\n\n1. No redundant development.\n2. Low coupling between modules.\n3. True single-responsibility design — each feature becomes its own **logic server**.\n4. Scale any module independently without code changes.\n5. Build up your own **ecosystem arsenal** of reusable components for competitive advantage.\n6. **Reduced code leak risk.** Monolithic projects put everything in one directory — one leak exposes everything. With modular servers, each developer only accesses their own module.\n7. Admins deploy the gateway and External Server on the internal network; developers code and test their own modules locally. Additional perks:\n - Client connections survive logic server restarts.\n - Developers don't need to run each other's modules.\n - Auto-generated docs handle inter-module integration.\n\n\n\n**Full-link distributed tracing.** Every request gets a [unique trace ID](https://iohao.github.io/game/docs/manual/trace) recorded across logs — filter by ID to instantly find what you need. ioGame's tracing works **across machines and processes**: from request entry to completion, every logic server touched is precisely recorded.\n\n\n\n**Rich communication models.** While most frameworks only offer push/broadcast, ioGame provides a complete set of [communication patterns](https://iohao.github.io/game/docs/manual/communication_model) — all supporting cross-process, cross-machine communication with full-link tracing:\n\n- **Client-facing models:**\n - [request/response](https://iohao.github.io/game/docs/communication/request_response)\n - request/void (fire-and-forget)\n - request/broadcast\n - [broadcast](http://localhost:3000/docs/communication/broadcast) (server push)\n- **Internal (server-to-server) models:**\n - [request/response](https://iohao.github.io/game/docs/communication/request_response)\n - request/void\n - [request/multiple_response](https://iohao.github.io/game/docs/communication/request_multiple_response) — fan-out to multiple logic servers of the same type\n - [EventBus](https://iohao.github.io/game/docs/communication/event_bus) — distributed event bus\n - [ExternalRegion](https://iohao.github.io/game/docs/communication/external_biz_region) — access External Servers\n\n\n\nSince ioGame 21, **virtual threads** are used for blocking inter-service communication, preventing business thread starvation and significantly boosting throughput.\n\n\n\n**Thread safety made easy.** The framework guarantees [per-player thread safety](https://iohao.github.io/game/docs/overall/thread_executor) — even across re-logins, the same thread handles that player's business. For multi-player scenarios (e.g., same room), [Domain Events](https://iohao.github.io/game/docs/extension_module/domain_event) provide a clean solution. ioGame's unique thread executor design makes writing **lock-free concurrent code** straightforward.\n\n\n\n**Lock-free concurrency.** ioGame's elegant thread executor design lets developers write high-concurrency code without locks — naturally and safely.\n\n\n\n**Protocol-agnostic connections.** Use **one codebase** to support TCP, WebSocket, and UDP simultaneously — no modifications needed. Connection types are extensible: when KCP or QUIC support lands, just switch — your business code stays untouched.\n\n\n\n**Flexible data protocols.** [Switch between Protobuf, JSON, and more](https://iohao.github.io/game/docs/manual/data_protocol) with a single line of code. No business method changes required.\n\n\n\n**Hot-swap protocols.** Add or remove protocols **without restarting** the External Server or Broker — no player disconnections, no fleet-wide restarts.\n\n\n\n**Protocol fragment solution.** Actions auto-box and unbox primitive types, solving the [protocol fragment](https://iohao.github.io/game/docs/manual/protocol_fragment) problem while making business code cleaner and boosting developer productivity.\n\n\n\n**[Same-process affinity](https://iohao.github.io/game/docs/manual_high/same_process).** Within a single process, Netty instances communicate via memory — no network overhead, blazing-fast data transfer. The framework intelligently routes requests to same-process logic servers first, falling back to other processes/machines only when needed.\n\n\n\n**Great developer experience.** ioGame ships with [JSR380 validation](https://iohao.github.io/game/docs/core/jsr380), [assertions + exception handling](https://iohao.github.io/game/docs/manual/assert_game_code), [code navigation](https://iohao.github.io/game/docs/core_plugin/action_debug), auto-boxing for primitives, and more — all designed to keep your business code clean and concise.\n\n\n\n**Extensible [plugin system](https://iohao.github.io/game/docs/manual/plugin_intro).** Built-in plugins include DebugInOut, action call statistics, thread monitoring, time-bucketed call analytics, and more. Combine monitoring plugins to catch **performance issues during development** — find and fix problems before they reach production.\n\n\n\n**Flexible deployment.** Run as a **single process** during development, deploy as **multi-process across machines** in production — switch freely without changing a line of code.\n\n\n\n**Secure by design.** Logic Servers [never expose ports](https://iohao.github.io/game/docs/overall/legacy_system#Usage-Management) — **port-scanning attacks are impossible.** No need to manage per-service ports or cloud firewall rules. This entire category of ops headaches simply **disappears**.\n\n\n\n**Realistic testing.** The [stress test & simulation module](https://iohao.github.io/game/docs/extension_module/simulation_client) goes beyond unit tests. It simulates real network conditions with continuous, interactive server communication and full automation support. Great for complex scenario testing and load validation.\n\n\n\n**Cost-effective at every stage.** ioGame reduces costs across learning, development, testing, deployment, scaling, and beyond. With equal resources, ioGame gives your team a competitive edge — and protects you from building value that only benefits others. See the full [cost analysis](https://iohao.github.io/game/services/cost_analysis).\n\n\n\n**Well-organized projects.** ioGame's thoughtful **route design** and elegant [access control](https://iohao.github.io/game/docs/external/access_authentication) naturally produce clean, maintainable codebases. Combined with [code organization conventions](https://iohao.github.io/game/docs/manual_high/code_organization), handoffs and long-term maintenance become much smoother. The deeper you go, the more you'll appreciate this.\n\n\n\n**Modern Java, modern performance.** ioGame requires **JDK 21+**, giving you access to **Generational ZGC** with **sub-millisecond** pause times and modern syntax. GC pauses become invisible — no stuttering, no crashes — like having a JVM tuning expert on your team.\n\n\n\n**In short**, ioGame is purpose-built for online game development. It lets you create high-performance, low-latency, easily scalable game servers while saving time and resources. The framework handles the complex, repetitive infrastructure so you can focus on what matters — your game. It provides **clear structural organization** for modules and development workflows, reducing long-term maintenance costs.\n\n\n\nWe believe you now have a solid overview of ioGame. There are many more features to discover as you dive deeper. Thank you for reading — we look forward to seeing what you build!\n\n---\n\n## Write Once, Generate Everywhere — A Massive Productivity Boost\n\nioGame is built around the principle of **code-as-documentation** and **methods-as-interfaces**.\n\n\n\n**Write once** means writing your Java business code a single time. **Generate everywhere** means automatically producing client interaction code for any frontend project.\n\n\n\nWrite your Java code once and generate unified interaction interfaces for [Godot](https://godotengine.org/), [UE](https://www.unrealengine.com/), [Unity](https://unity.com/), [CocosCreator](https://www.cocos.com/), [Laya](https://layaair.layabox.com/#/), [React](https://react.dev/), [Vue](https://vuejs.org/), [Angular](https://angular.dev/), and more.\n\n\n\nioGame generates **action, broadcast, and error code** interfaces for any frontend project. Write your business logic once — it works with all these game engines and modern frontend frameworks simultaneously.\n\n\n\n**Why generated client code matters:**\n\n1. **Eliminates boilerplate.** Client developers no longer write mountains of template code.\n2. **Crystal-clear semantics.** Generated interfaces explicitly define parameter types and whether to expect a response — no guesswork.\n3. **Type-safe parameters.** Precise interface definitions mean type-safe method signatures, fewer security risks, and **fewer integration bugs**.\n4. **Code is the documentation.** Generated code includes docs and usage examples — **zero learning cost**, even for newcomers.\n5. **Focus on business logic.** Client developers can ignore server communication plumbing and **spend their time on what matters**.\n6. **Smooth integration.** Using generated code feels **as natural as calling a local method** — minimal cognitive overhead for both teams.\n7. **Interface-oriented, not protocol-oriented.** A modern approach that replaces the traditional protocol-centric integration workflow.\n8. **Always in sync.** When your Java code changes, documentation and interfaces update automatically — **no separate docs to maintain**.\n\n\n\n## Architecture Overview\n\n> Lock-free, async, event-driven architecture. Truly lightweight — build a clustered, distributed game server with zero middleware.\n>\n> Decentralized cluster nodes, automated clustering, built-in load balancing, distributed deployment, dynamic machine scaling.\n\n| Component | Scaling | Responsibility |\n| ------------------------------------------------------------ | ------------ | -------------------------------- |\n| **ExternalServer** — [External Server](https://iohao.github.io/game/docs/overall/external_intro) | Distributed | Player connections & interaction |\n| **GameLogicServer** — [Game Logic Server](https://iohao.github.io/game/docs/overall/logic_intro) | Distributed | Business logic processing |\n| **BrokerCluster** — [Broker (Gateway)](https://iohao.github.io/game/docs/overall/broker_intro) | Clustered | Request scheduling & forwarding |\n\n\n\nFor details, see the [Architecture Guide](https://iohao.github.io/game/docs/overall/architecture_intro).\n\n------\n\n> The Broker (Gateway) runs as a **cluster** — typically stateless, focused on scheduling and forwarding.\n>\n> External Servers and Game Logic Servers use a **distributed** model, supporting multiple instances of the same type. When player counts grow, simply spin up more Logic Servers.\n>\n> **Example:** Two type-A Logic Servers (A-1, A-2) share requests via the gateway's random load-balancing strategy.\n>\n> Both External Servers and Logic Servers support dynamic addition and removal. **Zero-downtime updates** are built in: launch A-3 and A-4 with new features, then gracefully retire A-1 and A-2 — players won't notice a thing.\n>\n> The framework also supports [dynamic player-to-server binding](https://iohao.github.io/game/docs/manual/binding_logic_server) — once bound, all subsequent requests from that player route to the same Logic Server.\n>\n> **Beyond gaming:** ioGame works great for IoT too. Replace \"players\" with \"devices\" in the diagram — the architecture handles hundreds of millions of connections. IoT companies have been using ioGame successfully since 2022.\n\n\n\n**External Server**\n\nThe External Server manages persistent player connections. Say one server supports up to 5,000 connections — when you hit 7,000, just add another External Server to distribute the load.\n\nScaling External Servers provides natural load balancing and traffic control under high concurrency. Thanks to trivial scaling, supporting **millions** of concurrent players is entirely achievable.\n\nEven with multiple External Servers, developers don't need to track which server a player is connected to — broadcasts and pushes reach every player automatically. From the player's perspective, there's only one server. From the developer's perspective, the same is true.\n\nWondering about max connections per External Server? That's a Netty question — because under the hood, that's exactly what it is. If you know Netty, extending the External Server will feel second nature.\n\n\n\n## Quick Start\n\nHere's a simplified view of how a game engine interacts with the game server:\n\n\n\n> The game frontend and server communicate **bidirectionally**, exchanging business data encoded/decoded via `.proto` files. Protocol Buffers (PB) is currently the best choice for game data serialization, though JSON, XML, or custom formats are also supported since everything is transmitted as binary.\n>\n> **Game frontends** can be [Godot](https://godotengine.org/), [Unity](https://unity.cn/), [UE](https://www.unrealengine.com/zh-CN/), [Cocos Creator](https://www.cocos.com/), [Laya](https://layaair.layabox.com/#/), [FXGL](https://github.com/AlmasB/FXGL), or any other engine. The engine handles rendering; data exchange happens over TCP, UDP, etc.\n\n\n\n**Data Protocol**\n\nDefine two simple data protocols for client-server communication. These are jprotobuf objects — a simplified wrapper around Google Protobuf with equivalent performance.\n\nThink of them as DTOs — carriers for business data:\n\n```java\n@ProtobufClass\npublic class LoginVerifyMessage {\n public String jwt;\n}\n\n@ProtobufClass\npublic class UserMessage {\n public String name;\n}\n```\n\n\n\n**Action**\n\nHere's your server-side business logic. This code simultaneously supports TCP, WebSocket, and UDP — no changes needed:\n\n```java\n@Slf4j\n@ActionController(1)\npublic class DemoAction {\n @ActionMethod(0)\n public UserMessage here(LoginVerifyMessage message) {\n var userMessage = new UserMessage();\n userMessage.name = \"Michael Jackson, \" + message.jwt;\n return userMessage;\n }\n}\n```\n\n\n\nEach method (like `here`) is an [Action](https://iohao.github.io/game/docs/manual/action) — a unit of business logic.\n\nMethod parameters receive data from the frontend. The return value is automatically sent back to the client. You don't need to understand framework internals.\n\nNotice how this looks just like ordinary Java? That's intentional — and it **prevents class explosion**. If your job is writing game logic, your ioGame learning journey can stop right here.\n\n\n\n**Game programming really is this simple.**\n\n\n\n**Q: Am I ready to start building a game server?**\n\n> Yes. Yes you are.\n\n\n\n**Console Output Example**\n\nWhen an action is called, the console logs:\n\n```text\n┏━━━━━ Debug. [(DemoAction.java:5).here] ━━━━━ [cmd:1-0 65536] ━━━━━ [xxxLogicServer - id:[76526c134cc88232379167be83e4ddfc]\n┣ userId: 1\n┣ Params: message : LoginVerifyMessage(jwt=hello)\n┣ Response: UserMessage(name=Michael Jackson, hello)\n┣ Time: 1 ms (total business method execution time)\n┗━━━━━ [ioGameVersion] ━━━━━ [Thread:User-8-2] ━━━━━━━ [traceId:956230991452569600] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n```\n\n**What each field means:**\n\n- **Debug** `[(DemoAction.java:5).here]` — The action that ran, with line number. Click `DemoAction.java:5` in your IDE to jump straight to the code.\n- **userId** — The requesting player's ID.\n- **Params** — Input from the frontend.\n- **Response** — The return value, automatically pushed to the client.\n- **Time** — Execution duration — use this to spot and optimize slow logic.\n- **cmd** — The [route](https://iohao.github.io/game/docs/manual/cmd) (unique address) for this action.\n- **ioGameVersion** — Current framework version.\n- **Thread** — The thread that executed this action.\n- **traceId** — Unique per-request ID for distributed tracing.\n- **Logic Server** — Which Logic Server handled the request.\n\nThis visibility eliminates the most common time sinks in game development:\n\n- \"Did the client actually send the data?\" *(Parameter issues)*\n- \"Did the server actually respond?\" *(Response issues)*\n- \"Why is the client not getting responses?\" *(Timing issues)*\n\nCode navigation lets developers jump to any business method instantly — invaluable in team settings for understanding and modifying execution flow.\n\n\n\n## Who is ioGame For?\n\n1. Web developers curious about game server development.\n2. Developers new to the game industry.\n3. Anyone interested in game development — no prior experience needed.\n4. Learners who want to see design patterns applied in practice.\n5. Developers open to modern approaches.\n6. Anyone ready to leave legacy codebases behind.\n\n\n\nAt least one year of hands-on programming experience is recommended.\n"
},
{
"path": "README_CN.md",
"content": "
\n\n\nDocumentation: https://iohao.github.io/game/docs/intro\n\n## 愿景\n让网络游戏服务器的编程变得轻松简单。 改变行业现状，降低使用难度，让游戏开发领域的生产资料公有制！\n\n\n## 开放、自由、友好的开源协议\n- 过去、现在、将来都不会有商业版本，所有功能全部开源。\n- 承诺项目的维护周期是十年起步， 2022-03-01 起，至少十年维护期。\n- ioGame 是一个轻量级的网络编程框架，适用于**网络游戏服务器、物联网、内部系统**及各种需要长连接的场景。 源码完全开放、最新文档阅读完全开放、提供高质量的使用文档，使用完全自由、免费（遵守开源协议）。\n\n\n\n**友好的开源协议**\n\nioGame 使用 [AGPL3.0](https://www.gnu.org/licenses/agpl-3.0.txt) 开源协议，开发者在使用时需要遵守该协议。 在该协议下开发的项目是免费的，没有任何成本。\n\n同时，该协议对开发者更加友好，它确保了项目所有权在资本家和开发者之间共享。 这意味着，即使开发者带着项目离开公司或自行运营，也依然是合法的。\n\n与 Apache 2.0、MIT 等其他协议不同，那些协议下，一旦开发者离开公司，便会彻底失去对项目的控制权，难以获得任何实质性回报。 尤其是在开发阶段，程序员辛勤付出、996 加班，但当项目即将上线或刚上线时，却可能面临被裁的风险。 最终，他们只能眼睁睁看着自己倾注心血的成果被资本家掌控，而自己却一无所有。\n\n因此，采用 AGPL 3.0 协议的项目，由于开发者能共享所有权，更能激励程序员全身心投入，用心打磨项目。\n\n\n\n## 启动展示\n\nioGame 在内存占用、启动速度、打包等方面也是优秀的。\n- 内存方面：内存占用小。\n- 启动速度方面：应用通常会在 **0.x 秒**内完成启动。\n- 打包方面：打 jar 包后大约 **15MB** 。\n\n\n\n\n\n## 介绍\n\n你是否想要开发一个**高性能、稳定、易用、自带负载均衡、避免类爆炸设计、可跨进程跨机器通信、集群无中心节点、集群自动化、有状态多进程的分布式的**网络编程服务器呢？ 如果是的话，这里向你推荐一个由 java 语言编写的网络编程框架 ioGame。\n\n\n\nioGame 是一个轻量级的网络编程框架，适用于**网络游戏服务器、物联网、内部系统**及各种需要长连接的场景。\n\n\n\n**ioGame 有以下特点：**\n\n> 1. 真轻量级、无锁异步化、事件驱动的架构设计。\n> 2. 包体小、内存占用少、启动速度快。\n> 3. ioGame 是纯 javaSE 的，使得 ioGame 能与其他框架方便的进行集成、融合，如 Spring ...等。\n> 4. 在学习成本方面，ioGame 的学习成本非常低，可以说是**零学习成本**，即使没有游戏编程经验，也能轻松上手。开发者只需掌握普通的 java 方法或 webMVC 相关知识，就能用框架开发业务。\n> 5. ioGame 在架构上解决了传统框架所产生的 **N\\*N 问题**。\n> 6. 在轻量级方面，ioGame **不依赖任何第三方**中间件或数据库**就能支持集群、分布式**，只需要 java 环境就可以运行。\n> 7. 在架构灵活性方面，ioGame 的架构由三部分组成：1.游戏对外服、2.Broker（游戏网关）、3.游戏逻辑服。三者既可相互独立，又可相互融合，这意味着使用 ioGame 可以**适应任何类型的游戏**。\n> 8. 架构是可以动态扩缩的，游戏对外服、游戏逻辑服、Broker（游戏网关）都**支持动态增加和减少**。\n> 9. 在分布式开发体验方面，ioGame 支持多服单进程的启动方式，这使得开发者在开发和调试分布式系统时更加简单。\n> 10. 在生态规划方面，游戏逻辑服是支持独立运行，**从而实现功能模块化的可能性**。\n> 11. 具备全链路调用日志跟踪特性。\n> 12. 在通讯方式方面，提供多种通讯方式，且逻辑服之间可以相互跨机器通信。\n> 13. 在编码风格上，提供了类 MVC 的编码风格（无入侵的 Java Bean ），这种设计方式很好的**避免了类爆炸**。\n> 14. 在线程安全方面，框架为开发者解决了单个玩家的**并发问题**。\n> 15. 在连接方式方面，允许开发者**使用一套业务代码**，同时支持 TCP、WebSocket、UDP 等多种连接方式，无需进行任何修改，并且可扩展。\n> 16. 在数据协议方面，ioGame 让开发者**用一套业务代码**，就能轻松切换不同的数据协议，如 Protobuf、JSON 等，并且可扩展。\n> 17. 在增减协议方面，ioGame 可以让你在**新增或减少协议**时，**无需重启**游戏对外服与 Broker（游戏网关）。这样既能避免玩家断线，又能避免因新增、减少协议而重启所有机器的痛点。\n> 18. action 支持自动装箱、拆箱基础类型，用于解决[协议碎片](https://iohao.github.io/game/docs/manual/protocol_fragment)的问题。\n> 19. 业务框架提供了插件机制，插件是可插拨、可扩展的。\n> 20. 在部署方面，ioGame 支持**多服单进程**的方式部署，也支持**多服多进程**多机器的方式部署，在部署方式上可以随意的切换而不需要更改代码。\n> 21. 在安全方面，所有的游戏逻辑服不需要开放端口，**天然地避免了扫描攻击**。\n> 22. 在模拟客户端测试方面，ioGame 提供了压测&模拟客户端请求模块。该模块**可以模拟真实的网络环境**，并且在模拟测试的过程中与服务器的交互是可持续的、可互动的，同时也是支持自动化的。\n> 23. 框架为开发者提供了同步、异步、异步回调的方法，用于逻辑服之间的相互访问。\n> 24. 分布式事件总线支持（类似 MQ、Redis 发布订阅机制，可跨多个机器通信、可跨多个进程通信）。\n> 25. 提供优雅的路由访问权限控制。\n> 26. 具备智能的同进程亲和性。\n> 27. JSR380 验证、断言 + 异常机制 = 更少的维护成本。\n> 28. 一次编写到处对接，提升巨大的生产力，能为各客户端生成可交互的代码。你只需要编写一次 java 代码，就能为 Godot、UE、Unity、CocosCreator、Laya、React、Vue、Angular ...等项目生成统一的交互接口。\n\n\n\nioGame 在打包、内存占用、启动速度等方面也是优秀的。 打 jar 包后大约 **15MB**，应用通常会在 **0.x 秒**内完成启动，内存占用小。\n\n\n\n在生态融合方面，ioGame 可以很方便的[与 Spring 集成](https://iohao.github.io/game/docs/manual/integration_spring)（4 行代码）。 除了 Spring 外，还能与任何其他的框架做**融合**，如 Vert.x、Quarkus、Solon ...等，从而使用其他框架的相关生态。\n\n\n\n在学习成本方面，ioGame 的学习成本非常低，可以说是**零学习成本**，即使没有游戏编程经验也能轻松上手。 开发者只需掌握普通的 java 方法或 webMVC 相关知识，就能使用框架开发业务。\n\n\n\n在编码风格上，ioGame 为开发者提供了类 MVC 的编码风格（无入侵的 Java Bean ），这种设计方式很好的**避免了类爆炸**。 同时，框架为开发者提供了同步、异步、异步回调的方法，用于逻辑服之间的相互访问。 这使得开发者所编写的代码会非常的优雅，并且具备全链路调用日志跟踪。\n\n\n\n与客户端对接方面，ioGame 具备**一次编写到处对接**的能力，为客户端提供了代码生成的辅助功能，能够帮助客户端开发者减少巨大的工作量。 这将意味着，你只需要编写一次 java 代码，就能为 Godot、UE、Unity、CocosCreator、Laya、React、Vue、Angular ...等项目生成统一的交互接口。 ioGame 提供了多种语言的 SDK 支持及相关语言的[代码生成](https://iohao.github.io/game/docs/examples/code_generate)，分别是 C#、TypeScript、GDScript、C++，并支持扩展。\n\n\n\nioGame 在架构上解决了传统框架所产生的 **N\\*N 问题**（[与传统架构对比](https://iohao.github.io/game/docs/overall/legacy_system)）。 传统架构在扩展机器时，需要借助很多第三方中间件，如：Redis、MQ、ZooKeeper ...等，才能满足整体架构的运作。 通常，只要引入了需要安装的中间件才能做到扩展的，那么你的架构或者说框架，基本上与轻量级无缘了。\n\n\n\n在轻量级方面，ioGame **不依赖任何第三方**中间件或数据库**就能支持集群、分布式**，只需要 java 环境就可以运行。 这意味着在使用上简单了，在部署上也为企业减少了部署成本、维护难度。使用 ioGame 时，只需一个依赖即可获得整个框架， 而无需安装其他服务，如： Nginx、Redis、MQ、Mysql、ZooKeeper、Protobuf 协议编译工具 ...等。\n\n\n\n在[架构灵活性](https://iohao.github.io/game/docs/overall/deploy_flexible)方面，ioGame 的架构由三部分组成：1.游戏对外服、2.Broker（游戏网关）、3.游戏逻辑服。 三者既可相互独立，又可相互融合。 这意味着使用 ioGame 可以**适应任何类型的游戏**，因为只需通过调整部署方式，就可以满足不同类型的游戏需求。 在 ioGame 中进行这些调整工作非常简单，而且不会对现有代码产生不良影响。\n\n\n\n架构是可以动态扩缩的，游戏对外服、游戏逻辑服、Broker（游戏网关）都**支持动态增加和减少**。 无论未来玩家数量增加或减少，我们都能够轻松应对。 同时，架构是**支持玩家无感知更新**的，这得益于分布式设计。 举例来说，如果 A 类型的游戏逻辑服需要增加一些新功能，我们可以启动 A-3、A-4 等已经支持了新功能的服务器， 然后逐步将之前的 A-1 和 A-2 下线，从而实现了无感知的更新。\n\n\n\n在集群方面，ioGame 的 Broker （游戏网关）采用无中心节点、[自动化的集群设计](https://iohao.github.io/game/docs/examples/server/example_broker_cluster)，所有节点平等且自治，不存在单点故障。 集群能够**自动管理和弹性扩缩**，节点加入或退出时，能够自动保证负载均衡和数据一致性，不影响服务可用性。\n\n\n\n在分布式方面，ioGame 的逻辑服使用了分布式设计思想，将服务器分为[游戏对外服](https://iohao.github.io/game/docs/overall/external_intro)、[游戏逻辑服](https://iohao.github.io/game/docs/overall/logic_intro)等不同层次， 并且每一层都有明确的职责和接口。这样可以提高代码可读性和可维护性，并且方便进行**水平扩展**。\n\n\n\n在分布式开发体验方面，通常在开发分布式应用时是需要启动多个进程的。 这会让调试与排查问题变得非常困难，从而降低开发者的效率、增加工作量等，这也是很多框架都**解决不了的问题**，但 ioGame 做到了！ ioGame 支持多服单进程的启动方式，这使得开发者在开发和调试分布式系统时更加简单。\n\n\n\n在[生态规划](https://iohao.github.io/game/docs/manual_high/your_ecology)方面，我们的游戏逻辑服是支持独立运行的，只需接入 Broker（游戏网关）上， 就可以为玩家和其他游戏逻辑服提供功能上的扩展与增强。 我们可以将一些**游戏逻辑服组件化**，并制作成相对通用的组件，**从而实现功能模块化的可能性**。这么做有几个优点\n\n1. 避免一些重复开发的工作量。\n2. 减少各功能模块的耦合。\n3. 更符合单一职责的设计，将相对通用的功能扩展成一个个的**功能逻辑服**。如，公会逻辑服、好友逻辑服、登录逻辑服、抽奖逻辑服、公告逻辑服、排行榜逻辑服...等。\n4. 由于模块功能是独立，那么将来可以对任意的功能逻辑服进行扩容，且不需要改动任何代码。\n5. 这些组件化后的功能逻辑服就好比一件件武器，积累得足够多时就形成了自己的生态武器库，可以更好的帮助公司与同行竞争。\n6. **代码泄漏机率更小**。传统的游戏项目通常采用单机结构，把所有的代码放在一个目录中。这样做有很大的风险，因为如果代码泄漏了，就会泄漏整个项目的内容。当功能模块化后，可以让不同的开发人员只负责自己的游戏逻辑服模块，从而避免代码泄漏的风险和影响。\n7. 团队管理员只需要在内网服务器上部署一个游戏网关和游戏对外服，而开发人员就可以在本机上编码和测试自己的游戏逻辑服模块。这样还有以下好处\n - 游戏客户端不会因为游戏逻辑服的变更或重启而断开连接。\n - 开发人员不需要启动其他人的游戏逻辑服模块。\n - 开发人员可以通过 ioGame 自动生成的文档来进行模块间的对接。\n\n\n\nioGame 具备[全链路调用日志跟踪](https://iohao.github.io/game/docs/manual/trace)特性，这在分布式下非常的实用。 该特性为每个请求分配一个唯一标识，并记录在日志中，通过唯一标识可以快速的在日志中过滤出指定请求的信息。 ioGame 提供的全链路调用日志跟踪特性更是强大，**支持跨机器、跨进程**。 简单的说，从玩家的请求进来到结束，无论该请求经过了多少个游戏逻辑服，都能精准记录。\n\n\n\n在通讯方式方面，大部分框架只能支持推送（广播）这一类型的通讯方式。 ioGame 则提供了多种[通讯模型](https://iohao.github.io/game/docs/manual/communication_model)， 通过对各种通讯方式的组合使用，可以简单完成以往难以完成的工作， 并且这些通讯方式都支持跨进程、跨机器通信，且具备全链路调用日志跟踪。\n\n- 在客户端的角度，提供了如下的通讯模型\n - [request/response](https://iohao.github.io/game/docs/communication/request_response)，请求/响应\n - request/void，请求/无响应\n - request/broadcast，请求/广播响应\n - [broadcast](http://localhost:3000/docs/communication/broadcast)，广播\n- 内部通讯主要用于服务器内部之间的通信，跨服、跨进程通信。提供了如下的通讯模型\n - [request/response](https://iohao.github.io/game/docs/communication/request_response)，请求/响应\n - request/void，请求/无响应\n - [request/multiple_response](https://iohao.github.io/game/docs/communication/request_multiple_response)，同时请求同类型多个游戏逻辑服\n - [EventBus](https://iohao.github.io/game/docs/communication/event_bus)，分布式事件总线\n - [ExternalRegion](https://iohao.github.io/game/docs/communication/external_biz_region)，访问游戏对外服\n\n\n\n从 ioGame21 开始，框架添加了虚拟线程的相关支持。 各逻辑服之间通信阻塞部分使用虚拟线程，这样可以很好的避免阻塞业务线程，并大幅提高了框架的吞吐量。\n\n\n\n在线程安全方面，框架为开发者解决了单个玩家的**并发问题**。 即使玩家重新登录后，也会使用相同的线程来消费业务，并推荐使用[领域事件](https://iohao.github.io/game/docs/extension_module/domain_event)来解决同一房间或业务内多个玩家的并发问题。 [框架在线程的扩展性](https://iohao.github.io/game/docs/overall/thread_executor)上提供了友好的支持，开发者可以很容易的编写出无锁并发代码，这得益于 ioGame 独有的线程执行器设计与扩展。 换句话说，你不会因为并发问题烦恼。\n\n\n\n在无锁并发方面，ioGame 提供了优雅、独特的线程执行器设计。通过该特性，开发者能轻易的编写出无锁高并发的代码。\n\n\n\n在连接方式方面，ioGame 允许开发者**使用一套业务代码**，**同时支持**多种连接方式，无需进行任何修改。 ioGame 已经支持了 TCP、WebSocket 和 UDP 连接方式，并且也支持在这几种连接方式之间进行灵活切换。 连接方式是可扩展的，并且扩展操作也很简单，这意味着之后如果支持了 KCP、QUIC， 无论你当前项目使用的是 TCP、WebSocket、UDP，都可以切换成 KCP、QUIC。 即使切换到 KCP、QUIC 的连接方式，现有的业务代码也无需改变。\n\n\n\n在通信协议方面，ioGame 让开发者**用一套业务代码**，就能轻松[切换和扩展不同的数据协议](https://iohao.github.io/game/docs/manual/data_protocol)， 如 Protobuf、JSON 等。只需一行代码，就可以从 Protobuf 切换到 JSON，无需改变业务方法。\n\n\n\n在增减协议方面，ioGame 可以让你在**新增或减少协议**时，**无需重启**游戏对外服与 Broker（游戏网关）。 这样既能避免玩家断线，又能避免因新增、减少协议而重启所有机器的痛点。\n\n\n\n在协议碎片方面，action 支持自动装箱、拆箱基础类型特性，用于解决[协议碎片](https://iohao.github.io/game/docs/manual/protocol_fragment)的问题。 同时该特性除了能使你的业务代码更加清晰以外，还能大幅提高开发者在该环节的生产力。\n\n\n\n在[同进程亲和性](https://iohao.github.io/game/docs/manual_high/same_process)方面，在同一进程内， 不同 Netty 实例之间的通信，是通过内存进行传输的，不需要经过网络传输，数据传输速度极快。 同进程亲和性指的是，优先访问同进程内的游戏逻辑服，当同进程内没有能处理请求的游戏逻辑服时， 才会去其他进程或机器中查找能处理请求的游戏逻辑服。 简单点说，框架对于请求的处理很智能，会优先将请求给同进程内的逻辑服消费。\n\n\n\n在开发体验方面，ioGame 非常注重开发者的开发体验。 框架提供了 [JSR380 验证](https://iohao.github.io/game/docs/core/jsr380)、[断言 + 异常机制](https://iohao.github.io/game/docs/manual/assert_game_code)、[业务代码定位](https://iohao.github.io/game/docs/core_plugin/action_debug)， action 支持自动装箱、拆箱基础类型，用于解决协议碎片的问题 ...等。 诸多丰富的功能，使得开发者的业务代码更加的清晰、简洁。\n\n\n\n业务框架提供了[插件](https://iohao.github.io/game/docs/manual/plugin_intro)机制，插件是可插拨、可扩展的。 框架内置提供了 DebugInOut、action 调用统计、业务线程监控插件、各时间段调用统计插件...等插件。 不同的插件提供了不同的关注点，比如我们可以使用调用、监控等插件相互配合，可以让我们在开发阶段就知道**是否存在性能问题**。 合理利用好各个插件，可以让我们在开发阶段就能知道问题所在，提前发现问题，提前预防问题。\n\n\n\n在部署方面，ioGame 支持**多服单进程**的方式部署，也支持**多服多进程**多机器的方式部署，在部署方式上可以随意的切换而不需要更改代码。 日常中我们可以按照单体思维开发，到了生产可以选择性的使用多进程的方式部署。\n\n\n\n在安全方面，所有的游戏逻辑服[不需要开放端口，天然地避免了扫描攻击](https://iohao.github.io/game/docs/overall/legacy_system#Usage-Management)。 由于不需要为每个逻辑服分配独立的端口，那么我们在使用诸如云服务器之类的服务时，就不需要担心端口开放权限的问题了。 别小看这一个环节，通常这些小细节最浪费开发者的时间。 由于我们不需要管理这些 IP:Port，**这部分的工作量就自然地消失了**。\n\n\n\n在模拟客户端测试方面，ioGame 提供了[压测&模拟客户端请求](https://iohao.github.io/game/docs/extension_module/simulation_client)模块。 此模块是用于模拟客户端，简化模拟工作量，只需要编写对应请求与回调。 除了可以模拟简单的请求外，通常还可以做一些复杂的请求编排，并支持复杂业务的压测。 **与单元测试不同的是，该模块可以模拟真实的网络环境，并且在模拟测试的过程中与服务器的交互是可持续的、可互动的，同时也是支持自动化的**。\n\n\n\n使用 ioGame，可以显著的帮助企业减少巨额成本。 文档中，**成本**关键字提到了很多次，各个阶段均有关联，包括了学习、研发、测试、部署、扩展、投入 ...等各阶段。 在同等资源的竞争下，使用 ioGame 能为公司节省更多的资源，从而提高了自身的生存率。 更重要的是避免了为其他公司做嫁衣的可能性，具体可阅读[成本分析案例](https://iohao.github.io/game/services/cost_analysis)。\n\n\n\n开发者基于 ioGame 编写的项目模块，通常是条理清晰的，得益于框架对**路由的合理设计**，同时也为路由提供了优雅的[访问权限控制](https://iohao.github.io/game/docs/external/access_authentication)。 当我们整理好这些模块后，对于其他开发者接管项目或后续的维护中，会是一个不错的帮助（[代码组织与约定](https://iohao.github.io/game/docs/manual_high/code_organization)）。 或许现阶段你感受不到这块的威力，随着你深入地使用实践就能体会到这么设计的诸多好处与优势。\n\n\n\n开发者基于 ioGame 编写的项目，通常是语法简洁的、高性能的、低延迟的。 框架最低要求使用 **JDK21**，这样即可以让项目享受到**分代 ZGC** 带来的改进，还能享受语法上的简洁。 分代 ZGC 远低于其**亚毫秒级**暂停时间的目标，可以在不影响游戏速度的情况下，清理掉多余的内存。 这样就不会出现卡顿或者崩溃的问题了，相当于在项目中变相的引入了一位 JVM 调优大师。\n\n\n\n综上所述，ioGame 是一个非常适合网络游戏开发的框架。可以让你轻松地创建高性能、低延迟、易扩展的游戏服务器，并且节省时间和资源。 如果你想要快速地开发出令人惊艳的网络游戏，请不要犹豫，立即选择 ioGame 吧！ 框架屏蔽了很多复杂且重复性的工作，并可为项目中的功能模块结构、开发流程等进行**清晰的组织定义**，减少了后续的项目维护成本。\n\n\n\n框架在开发、部署、压测&模拟测试 ...等，各个阶段都提供了很好的支持。 相信你已经对 ioGame 有了一个初步的了解，虽然还有很多丰富的功能与特性没有介绍到，但你可以通过后续的实践过程中来深入了解。 感谢你的阅读，并期待你使用 ioGame 来打造自己的游戏服务器。\n\n---\n\n## 一次编写到处对接，提升巨大的生产力\n\nioGame 是非常注重开发体验的，代码注释即文档、方法即交互接口的原则。\n\n\n\nioGame 具备一次编写到处对接的能力，从而让你们团队提升巨大的生产力。 **一次编写**指的是编写一次 java 业务代码，而**到处对接**则是指为不同的前端项目生成与服务器交互的代码。\n\n\n\n你只需要编写一次 java 代码，就能为 [Godot](https://godotengine.org/)、 [UE](https://www.unrealengine.com/)、 [Unity](https://unity.com/)、 [CocosCreator](https://www.cocos.com/)、 [Laya](https://layaair.layabox.com/#/)、 [React](https://react.dev/)、 [Vue](https://vuejs.org/)、 [Angular](https://angular.dev/) ...等项目生成统一的交互接口\n\n\n\nioGame 能为各种前端项目生成 **action、广播、错误码** 相关接口代码。 这将意味着，你只需要编写一次业务代码，就可以同时与这些游戏引擎或现代化的前端框架交互。\n\n\n\n前端代码生成的几个优势\n\n1. 帮助客户端开发者减少巨大的工作量，**不需要编写大量的模板代码**。\n2. **语义明确，清晰**。生成的交互代码即能明确所需要的参数类型，又能明确服务器是否会有返回值。这些会在生成接口时就提前明确好。\n3. 由于我们可以做到明确交互接口，进而可以明确参数类型。这使得**接口方法参数类型安全、明确**，从而有效避免安全隐患，从而**减少联调时的低级错误**。\n4. 减少服务器与客户端双方对接时的沟通成本，代码即文档。生成的联调代码中有文档与使用示例，方法上的示例会教你如何使用，即使是新手也能做到**零学习成本**。\n5. 帮助客户端开发者屏蔽与服务器交互部分，**将更多的精力放在真正的业务上**。\n6. 为双方联调减少心智负担。联调代码使用简单，**与本地方法调用一般丝滑**。\n7. 抛弃传统面向协议对接的方式，转而**使用面向接口方法的对接方式**。\n8. 当我们的 java 代码编写完成后，我们的文档及交互接口可做到同步更新，**不需要额外花时间去维护对接文档及其内容**。\n\n\n\n## 架构简图\n\n> 无锁异步化、事件驱动的架构设计；真轻量级，无需依赖任何第三方中间件或数据库就能搭建出一个集群、分布式的网络游戏服务器。\n>\n> 集群无中心节点、集群自动化、自带负载均衡、分布式支持、可动态增减机器。\n\n| 名称 | 扩展方式 | 职责 |\n| ------------------------------------------------------------ | -------- | ---------------- |\n| **ExternalServer**，[游戏对外服](https://iohao.github.io/game/docs/overall/external_intro) | 分布式 | 与玩家连接、交互 |\n| **GameLogicServer**，[游戏逻辑服](https://iohao.github.io/game/docs/overall/logic_intro) | 分布式 | 处理具体业务逻辑 |\n| **BrokerCluster**，[Broker（游戏网关）](https://iohao.github.io/game/docs/overall/broker_intro) | 集群 | 调度和转发任务 |\n\n\n\n更详细的介绍请阅读[架构介绍](https://iohao.github.io/game/docs/overall/architecture_intro)。\n\n------\n\n> 从图中可以看出，游戏网关支持以集群方式启动多个实例。这个设计选择了集群的方式，因为游戏网关通常是无状态的，主要用于调度和转发任务\n>\n> 而游戏对外服、游戏逻辑服使用分布式设计，支持启动多个相同类型的服务。这意味着，当玩家数量增加时，我们可以轻松增加相应类型的游戏逻辑服以处理更多请求。\n>\n> 以游戏逻辑服为例，假设我们启动了两个 A 类型的游戏逻辑服，分别为 A-1 和 A-2。当玩家向 A 类型的游戏逻辑服发起多次请求时，游戏网关会使用默认的随机负载策略将请求分配给 A-1 和 A-2 来处理。\n>\n> 现在我们明白，游戏对外服和游戏逻辑服都支持动态增加和减少。无论未来玩家数量增加或减少，我们都能够轻松应对。架构是**支持玩家无感知更新**的，这得益于分布式设计。举例来说，如果 A 类型的游戏逻辑服需要增加一些新功能，我们可以启动 A-3、A-4 等已经支持了新功能的服务器，然后逐步将之前的 A-1 和 A-2 下线，从而实现了无感知的更新。\n>\n> 此外，框架还支持玩家[动态绑定游戏逻辑服](https://iohao.github.io/game/docs/manual/binding_logic_server)。玩家与游戏逻辑服绑定后，之后的请求都由该游戏逻辑服来处理。\n>\n> 除了游戏之外，ioGame 也适用于物联网相关项目。只需将图中的玩家视为具体的设备，即使存在数亿个设备，ioGame 的架构也可以轻松支持。从 2022 年开始，已经有一些物联网公司开始采用这一解决方案，并得到了很好的体验。\n\n\n\n**游戏对外服**\n\n游戏对外服主要负责与用户（玩家）的长连接，先来个假设，假如我们的一台硬件支持我们建立用户连接的上限是 5000 人， 当用户量达到 7000 人时，我们可以多加一个对外服务器来进行分流减压。\n\n通过增加游戏对外服的数量，可以有效地进行连接的负载均衡和流量控制，使得系统能够更好地承受高并发的压力。 由于游戏对外服扩展的简单性，意味着支持同时在线玩家可以轻松的达到百万、千万甚至更多。\n\n即使我们启动了多个游戏对外服，开发者也不需要关心这些玩家连接到了哪个游戏对外服的问题， 这些玩家总是能接收到广播（推送）消息的，因为框架已经把这些事情给做了。 在玩家的角度我们只有“一个”服务器，同样的，在开发者的角度我们只有“一个”游戏对外服。\n\n通常，有些开发者想知道游戏对外服最大支持多少玩家连接。 关于这个问题，只需要搜索 Netty 相关知识即可，因为游戏对外服本质上是 Netty。\n\n同样的，如果开发者已经熟悉了 Netty 相关知识，那么在游戏对外服的扩展上也会变得非常的容易。\n\n\n\n## 快速入门\n\n下面是游戏引擎与游戏服务器的业务交互简图。\n\n\n\n> 抽象的说，游戏前端与游戏服务器的的交互由上图组成。 游戏前端与游戏服务器可以自由地**双向交互**，即发送和接收业务数据。 业务数据由 .proto 文件作为载体，在前端和后端之间进行编码和解码。 .proto 文件是对业务数据的描述载体，定义了数据类型和消息类型，以及它们的属性和规则。\n>\n> 通过这种方式，游戏前端和游戏服务端可以建立连接，并开始相互传递业务数据，处理各自的业务。 以上是对游戏前端与游戏服务器之间交互方式的介绍。 接下来，我们将编写一个简单的游戏业务处理示例，并定制一个适合我们需求的业务数据协议。\n>\n> **协议文件**是对业务数据的描述载体，用于游戏前端与游戏服务器的数据交互。 Protocol Buffers 是 Google 开发的一种数据描述语言，也简称 PB。 协议文件描述还可以是 json、xml 或者任意自定义的，因为最后传输时会转换为二进制，但游戏开发中 PB 是目前的最佳选择。\n>\n> **游戏前端**的展现可以是 [Godot](https://godotengine.org/)、 [Unity](https://unity.cn/)、 [UE](https://www.unrealengine.com/zh-CN/)、 [Cocos Creator](https://www.cocos.com/)、 [Laya](https://layaair.layabox.com/#/)、 [FXGL](https://github.com/AlmasB/FXGL) 或者其他的游戏引擎。 这些游戏引擎只是展现游戏画面的一种形式，数据交互则由通信来完成（TCP、UDP ...等）。\n\n\n\n**数据协议**\n\n现在，我们定义两个数据协议，用于客户端与服务器的数据交互。 这是一个 jprotobuf 的 pb 对象，jprotobuf 是对 google protobuf 的简化使用，性能同等。\n\n\n\n可以把这理解成 DTO 业务数据载体等，其主要目的是用于业务数据的传输。\n\n```java\n@ProtobufClass\npublic class LoginVerifyMessage {\n public String jwt;\n}\n\n@ProtobufClass\npublic class UserMessage {\n public String name;\n}\n```\n\n\n\n**Action**\n\n游戏服务器的编程，游戏服务器接收业务数据后，对业务数据进行处理。 下面这段代码可以同时支持 TCP、WebSocket、UDP 通信方式。\n\n```java\n@Slf4j\n@ActionController(1)\npublic class DemoAction {\n @ActionMethod(0)\n public UserMessage here(LoginVerifyMessage message) {\n var userMessage = new UserMessage();\n userMessage.name = \"Michael Jackson, \" + message.jwt;\n return userMessage;\n }\n}\n```\n\n\n\n一个方法（here）在业务框架中表示一个 [Action](https://iohao.github.io/game/docs/manual/action)（业务动作）。\n\n方法声明的参数是用于接收前端传入的业务数据，在方法 return 时，数据就可以被游戏前端接收到。 程序员可以不需要关心业务框架的内部细节。\n\n从上面的示例可以看出，这和普通的 java 类并无区别，同时这种设计方式**避免了类爆炸**。 如果只负责编写游戏业务，那么对于业务框架的学习可以到此为止了。\n\n\n\n**游戏编程就是如此简单！**\n\n\n\n**问：我可以开始游戏服务器的编程了吗？**\n\n> 是的，你已经可以开始游戏服务器的编程了。\n\n\n\n**访问示例（控制台）**\n\n当访问 action 业务方法时，控制台将会打印的日志输出如下\n\n```text\n┏━━━━━ Debug. [(DemoAction.java:5).here] ━━━━━ [cmd:1-0 65536] ━━━━━ [xxx逻辑服 - id:[76526c134cc88232379167be83e4ddfc]\n┣ userId: 1\n┣ 参数: message : LoginVerifyMessage(jwt=hello)\n┣ 响应: UserMessage(name=Michael Jackson, hello)\n┣ 时间: 1 ms (业务方法总耗时)\n┗━━━━━ [ioGameVersion] ━━━━━ [线程:User-8-2] ━━━━━━━ [traceId:956230991452569600] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n```\n\n**控制台打印说明**\n\n- **Debug**. [(DemoAction.java:5).here] : 表示执行业务的是 DemoAction 类下的 here 方法，5 表示业务方法所在的代码行数。在工具中点击控制台的 DemoAction.java:5 这条信息，就可以跳转到对应的代码中（快速导航到对应的代码），这是一个开发良好体验的开始！\n- **userId** : 当前发起请求的 用户 id。\n- **参数** : 通常是游戏前端传入的值。\n- **响应** : 通常是业务方法返回的值 ，业务框架会把这个返回值推送到游戏前端。\n- **时间** : 执行业务方法总耗时，我们可根据业务方法总耗时的时长来优化业务。\n- **路由信息** : [cmd - subCmd][路由](https://iohao.github.io/game/docs/manual/cmd)是唯一的访问地址。\n- **ioGameVersion** : 表示当前所使用的 ioGame 版本。\n- **线程** : 当前执行 action 所使用的线程。\n- **traceId** : 全链路调用日志跟踪 id，每个请求唯一。（该特性在分布式下非常实用）\n- **逻辑服** : 当前游戏逻辑服的 id\n\n有了以上信息，游戏开发者可以很快的定位问题。 如果没有可视化的信息，开发中会浪费很多时间在前后端的沟通上。问题包括：\n\n- 是否传参问题 （游戏前端说传了）\n- 是否响应问题（游戏后端说返回了）\n- 业务执行时长问题 （游戏前端说没收到响应， 游戏后端说早就响应了）\n\n其中代码导航可以让开发者快速的跳转到业务类对应代码中， 在多人合作的项目中可以快速的知道业务经过了哪些方法的执行，使得我们可以快速的进行阅读或修改。\n\n\n\n## 适合人群\n\n1. 长期从事 web 内部系统开发人员， 想了解游戏的。\n2. 刚从事游戏开发的。\n3. 未从事过游戏开发，但却对其感兴趣的。\n4. 对设计模式在实践中的应用有兴趣的学习者。\n5. 可以接受新鲜事物的。\n6. 想放弃祖传代码的。\n\n\n\n推荐实际编程经验一年以上的人员。\n\n"
},
{
"path": "changeLog_ioGame.md",
"content": "文档与日志\n- [框架版本更新日志](https://iohao.github.io/game/docs/version_log)\n- [ioGame 真.轻量级网络编程框架 - 在线使用文档 ](https://game.iohao.com/)\n\n\n> ioGame 每月会发 1 ~ 2 个版本，通常在大版本内升级总是兼容的，如 21.1 升级到任意 21.x 的高版本。\n\n### 2025-08-11 - v21.30\nhttps://github.com/iohao/ioGame/releases/tag/21.30\n\n**Version update summary**\n\n> 1. fix(generate-code): [#490](https://github.com/iohao/ioGame/issues/490) Fixed the escaping of special characters in the Listener exampleCode for the code generation module. 修复 C# 代码生成时的转义字符\n\n\n### 2025-07-19 - v21.29\nhttps://github.com/iohao/ioGame/releases/tag/21.29\n\n**Version update summary**\n\n> 1. [#473](https://github.com/iohao/ioGame/issues/473) fix(core): Change the method name from DataSelfEncode getEncodeData to encodeData to avoid JSON serialization.\n> 2. fix(doc): [#459](https://github.com/iohao/ioGame/issues/459) Supporting the referencing of classes within a JAR file in a multi-module Gradle environment.\n> 3. feat(generate-code): [#452](https://github.com/iohao/ioGame/issues/452)\n> 4. fix(generate-code): broadcast_action_example_action.txt、broadcast_action_example.txt\n> 5. feat(external): [#469](https://github.com/iohao/ioGame/issues/469) Add HttpFallbackHandler to determine if it's a WebSocket upgrade request.\n> 6. perf(doc): Pre-create the Pb for the BroadcastDocument dataClass.\n\n**[other updates]**\n\nUpgrade reactor-netty 1.2.7、commons-io 2.19.0\n\n\n### 2025-06-17 - v21.28\nhttps://github.com/iohao/ioGame/releases/tag/21.28\n\n**Version update summary**\n\n> 1. feat(room): The room supports convenient operations. \n> 2. Deprecated RoomStatusEnum. \n> 3. feat(room): The room supports convenient broadcastRange. \n> 4. docs(all): Update documentation link (https://iohao.github.io/game). \n> 5. [#451](https://github.com/iohao/ioGame/issues/451) Refactor the usage documentation to use the new access address: https://iohao.github.io/game/ .\n\n------\n\n**[other updates]**\n\n```xml\n4.1.122.Final\n```\n\n------\n\n### 2025-05-09 - v21.27\n\nhttps://github.com/iohao/ioGame/releases/tag/21.27\n\n\n**Version update summary**\n\n> 1. feat(generate-code): #449 Supports GDScript GenerateCode\n> 2. #444 Provides GDScript SDK\n> 3. #448 Provides GDScript Example with ioGame\n> 4. perf(core): ActionCommandDocKit\n\n------\n\n\n\n**feat(generate-code)**: #449 Supports GDScript GenerateCode\n\nAbout examples: https://github.com/iohao/ioGameSdkGDScriptExampleGodot\n\n\n\n```java\npublic final class GenerateTest {\n // setting root path\n static String rootPath = \"/Users/join/gitme/ioGame-sdk/\";\n\n public static void main(String[] args) {\n // CHINA or US\n Locale.setDefault(Locale.CHINA);\n\n // Load the business framework of each gameLogicServer\n // cn: 加载游戏逻辑服的业务框架\n yourListLogic().forEach(BrokerClientStartup::createBarSkeleton);\n\n /*\n * Generate actions, broadcasts, and error codes.\n * cn: 生成 action、广播、错误码\n */\n \n // ----- About generating GDScript code -----\n generateCodeGDScriptGodot();\n\n // Added an enumeration error code class to generate error code related information\n IoGameDocumentHelper.addErrorCodeClass(YourGameCodeEnum.class);\n // Generate document\n IoGameDocumentHelper.generateDocument();\n }\n\n private static void generateCodeGDScriptGodot() {\n var documentGenerate = new GDScriptDocumentGenerate();\n // By default, it will be generated in the target/code directory\n // cn: 设置代码生成所存放的路径，如果不做任何设置，将会生成在 target/code 目录中\n String path = rootPath + \"ioGameSdkGDScriptExampleGodot/gen/code\";\n documentGenerate.setPath(path);\n\n IoGameDocumentHelper.addDocumentGenerate(documentGenerate);\n }\n}\n```\n\n\n\n\n\n\n### 2025-04-30 - v21.26\n\nhttps://github.com/iohao/ioGame/releases/tag/21.26\n\n**Version update summary**\n\n> 1. refactor(Code generation): Code generation supports importing multiple .proto files\n> 2. refactor(i18n): #376\n\n------\n\n\nSupports importing multiple .proto files\n\n```java\npublic interface SdkProtoFile {\n String fileName = \"common.proto\";\n String filePackage = \"common\";\n\n String fileName2 = \"common2.proto\";\n String filePackage2 = \"common2\";\n}\n\n@ToString\n@ProtobufClass\n@FieldDefaults(level = AccessLevel.PUBLIC)\n@ProtoFileMerge(fileName = SdkProtoFile.fileName, filePackage = SdkProtoFile.filePackage)\npublic final class LoginVerifyMessage {\n /** jwt */\n String jwt;\n}\n\n@ToString\n@ProtobufClass\n@FieldDefaults(level = AccessLevel.PUBLIC)\n@ProtoFileMerge(fileName = SdkProtoFile.fileName2, filePackage = SdkProtoFile.filePackage2)\npublic final class BulletMessage {\n /** id */\n int bulletId;\n /** bullet name */\n String name;\n}\n```\n\n\n**[other updates]**\n\n```xml\n4.1.121.Final\n```\n\n \n\n\n\n### 2025-03-20 - v21.25\n\nhttps://github.com/iohao/ioGame/releases/tag/21.25\n\n**Version update summary**\n\n> 1. fix(broker): DefaultWithElementSelector\n> 2. refactor(net): enhance ResponseCollectItemMessage\n> 3. refactor(core): FlowContext add the createResponseMessage method\n\n------\n\n**[other updates]**\n\n```xml\n4.1.119.Final\n```\n\n \n\n### 2025-02-12 - v21.24\n\nhttps://github.com/iohao/ioGame/releases/tag/21.24\n\n**Version update summary**\n\n> 1. refactor(client): Client support boxing and unboxing\n> 2. refactor(core): FlowContextKit add ofFlowContext method\n> 3. refactor(room): room add getPlayerBySeat method\n> 4. fix(core): [#425](https://github.com/iohao/ioGame/issues/425) When there is a method with the same name as the action, the `actionMethodIndex` is not obtained correctly.\n> 5. refactor(core): MethodParser add parseData method\n\n\n------\n\n\n\n**[client]** Client support boxing and unboxing.\n\n```java\n// my client，support：int、long、boolean、String、List\npublic final class MyInputCommandRegion extends AbstractInputCommandRegion {\n @Override\n public void initInputCommand() {\n this.inputCommandCreate.cmd = 1;\n\t\t// Client support boxing and unboxing\n ofCommand(2).setTitle(\"enterRoom\").setRequestData(() -> {\n // enterRoom\n long roomId = 2;\n return roomId;\n });\n \n // or \n ofCommand(2).setTitle(\"enterRoom\").setRequestData(() -> {\n // enterRoom\n return LongValue.of(2);\n });\n }\n}\n\n// my action\n@ActionController(1)\npublic final class MyAction {\n /**\n * enterRoom\n *\n * @param roomId roomId\n */\n @ActionMethod(2)\n public void enterRoom(long roomId) {\n }\n}\n```\n\n\n\n------\n\n**[other updates]**\n\n```xml\n4.1.117.Final\n```\n\n------\n\n\n\n\n\n### 2025-01-08 - v21.23\n\nhttps://github.com/iohao/ioGame/releases/tag/21.23\n\n\n**Version update summary**\n\n> 1. perf(room): OperationHandler adds the processVerify method to control whether the process method is executed, and deprecates the verify method, which is replaced by processVerify.\n> 2. perf(core): Optimize BoolValue and reduce the creation of objects\n> 3. perf(net-core): Enhance the invokeModuleMessage and invokeModuleCollectMessage methods of the BrokerClientItem. The return value must not be null, and error information is added.\n> 4. fix(generate-code): action_method_void.txt\n> 5. perf(doc): GameCode Support single parameter construction method\n> 6. perf(kit): [#412](https://github.com/iohao/ioGame/issues/412)\n> 7. perf(room): Player adds isRobot method. Room adds methods to distinguish between real players and robot players.\n> 8. refactor(proto): [#414](https://github.com/iohao/ioGame/issues/414) Enumeration supports custom value\n> 9. perf(room): room add hasSeat、isRealPlayer method\n> 10. refactor(kit): RandomKit add randomLong method\n> 11. refactor(core): Because the FlowContext method name setUserId is ambiguous, the method name is deprecated.\n>\n> 1. Deprecated FlowContext setUserId method; see bindingUserId.\n> 2. Deprecated FlowContext setUserIdAndGetResult method; see bindingUserIdAndGetResult.\n> 12. refactor(core): broadcastMe Added Tip: Please bind UserId before using this method, see FlowContext.bindingUserId.\n> 13. perf(proto): Generate .proto files in parallel\n> 14. refactor(proto): ProtoGenerateFile supports adding multiple proto packages\n> 15. refactor(kit): TaskKit supports setting Timer\n> 16. refactor(room): Deprecated OperationHandler verify, see processVerify\n> 17. refactor(room): Add OperationCode and enhance Operation\n\n\n------\n\n\n\nAbout **[core]** \n\nThe name of the FlowContext setUserId method is ambiguous. This method is deprecated and replaced by the bindingUserId method.\n\n```java\nflowContext.setUserId(userId); // Deprecated\nflowContext.bindingUserId(userId); // now\n```\n\n\n\nAbout **[kit]** \n\nTaskKit supports setting Timer\n\n```java\nTaskKit.setTimer(new HashedWheelTimer(17, TimeUnit.MILLISECONDS));\n```\n\n\n\nAbout **[room]** \n\n1. Add hasSeat method to room to check whether there are any empty seats in the room.\n2. Room add isRealPlayer method.\n3. Add isRobot method to Player, and add method to distinguish real players from robot players to Room.\n4. Add OperationCode and enhance Operation\n5. Add processVerify method to OperationHandler to control whether to execute process method, and deprecate verify method, replaced by processVerify.\n\nWhen processVerify returns false, process method will not be executed. There is an assertion mechanism in processVerify, and when there is no seat, an error code will be sent to the client to prompt the player.\n\n```java\npublic final class EnterRoomOperationHandler implements OperationHandler {\n @Override\n public boolean processVerify(PlayerOperationContext context) {\n \n // assert room spaceSize\n Room room = context.getRoom();\n GameCode.roomSpaceSizeNotEnough.assertTrue(room.hasSeat());\n\n long userId = context.getUserId();\n long score = AccountKit.getScore(userId);\n \n return score > 500;\n }\n\n @Override\n public void process(PlayerOperationContext context) {\n Room room = context.getRoom();\n ... enterRoom\n }\n}\n```\n\n\n\nExample of combining OperationCode with enumeration\n\n```java\n@ProtobufClass\n@ProtoFileMerge(fileName = FileMerge.fileName, filePackage = FileMerge.filePackage)\npublic enum MyOperation implements OperationCode {\n /** quitRoom */\n quitRoom,\n /** inRoom */\n inRoom\n ;\n\n final int operationCode;\n\n FairOperation() {\n this.operationCode = OperationCode.getAndIncrementCode();\n }\n\n @Override\n public int getOperationCode() {\n return operationCode;\n }\n}\n\n// config\npublic void configOperation() {\n RoomService roomService = ...\n OperationFactory factory = roomService.getOperationFactory();\n\n // mappingUser operation\n factory.mappingUser(MyOperation.inRoom, new InRoomOperationHandler());\n factory.mappingUser(MyOperation.quitRoom, new QuitRoomOperationHandler());\n}\n```\n\n\n\nAbout **[proto]** \n\n1. Optimize .proto generation and process file generation in parallel.\n\n2. ProtoGenerateFile supports adding multiple proto packages\n\nSupports adding multiple proto packages to better support modularization\n\n```java\n private static void generateProtoFile() {\n\n String generateFolder = \"/Users/join/gitme/game/MyGames/proto\";\n List protoPackageList = List.of(\"com.iohao.happy.robot\"\n ,\"com.iohao.happy.email\");\n\n var protoGenerateFile = new ProtoGenerateFile()\n // Generate the directory where the .proto file is stored\n .setGenerateFolder(generateFolder)\n // The package name to be scanned\n .addProtoPackage(protoPackageList)\n .addProtoPackage(\"com.iohao.happy.common.provide.proto\");\n\n // generate .proto \n protoGenerateFile.generate();\n }\n```\n\n\n\n3. Enumeration supports custom values, java code and generated .proto\n\n```java\n@ProtobufClass\n@ProtoFileMerge(fileName = TempProtoFile.fileName, filePackage = TempProtoFile.filePackage)\npublic enum AnimalTypeEnum implements EnumReadable {\n /** the cat */\n cat(0),\n /** the tiger */\n tiger(10),\n ;\n\n final int value;\n\n AnimalTypeEnum(int value) {\n this.value = value;\n }\n\n @Override\n public int value() {\n return this.value;\n }\n}\n```\n\n.proto\n\n```protobuf\n// TestAnimalTypeEnum\nenum AnimalTypeEnum {\n // the cat\n cat = 0;\n // the tiger\n tiger = 10;\n}\n```\n\n\n------\n\n**[other updates]**\n\n```xml\n4.1.116.Final\n```\n\n------\n\n\n\n### 2024-12-02 - v21.22\n\nhttps://github.com/iohao/ioGame/releases/tag/21.22\n\n**Version update summary**\n\n> 1. perf(core): DefaultActionMethodParamParser\n> 1. fix(kit): #407 ClassRefInfoKit invokeSetter\n> 1. #376 i18n DefaultUserHook\n> 1. feat(GenerateCode): #329 Added TypeScript code generation TypeScriptDocumentGenerate, which can generate interactive code for CocosCreator、Vue、Angular.\n\n\n------\n\n\n\n**feat(GenerateCode)**: #329 Added TypeScript code generation TypeScriptDocumentGenerate, which can generate interactive code for CocosCreator、Vue、Angular.\n\n\n\nAbout examples\n\n1. ioGameServerExample: https://github.com/iohao/ioGameExamples/tree/main/SdkExample\n2. CocosCreatorExample: https://github.com/iohao/ioGameSdkTsExampleCocos\n3. VueExample: https://github.com/iohao/ioGameSdkTsExampleVue\n4. HtmlExample: https://github.com/iohao/ioGameSdkTsExampleHtml\n5. AngularExample: https://github.com/iohao/ioGameSdkTsExampleAngular\n\n```java\npublic final class GenerateTest {\n // setting root path\n static String rootPath = \"/Users/join/gitme/ioGame-sdk/\";\n\n public static void main(String[] args) {\n // CHINA or US\n Locale.setDefault(Locale.CHINA);\n\n // Load the business framework of each gameLogicServer\n // 加载游戏逻辑服的业务框架\n yourListLogic().forEach(BrokerClientStartup::createBarSkeleton);\n\n /*\n * Generate actions, broadcasts, and error codes.\n * cn: 生成 action、广播、错误码\n */\n \n // About generating TypeScript code\n// generateCodeVue();\n// generateCodeAngular();\n// generateCodeHtml();\n generateCocosCreator();\n\n // Added an enumeration error code class to generate error code related information\n IoGameDocumentHelper.addErrorCodeClass(YourGameCodeEnum.class);\n // Generate document\n IoGameDocumentHelper.generateDocument();\n }\n\n private static void generateCodeVue() {\n var documentGenerate = new TypeScriptDocumentGenerate();\n\n // 设置代码生成所存放的路径，如果不做任何设置，将会生成在 target/code 目录中\n // By default, it will be generated in the target/code directory\n String path = rootPath + \"ioGameSdkTsExampleVue/src/assets/gen/code\";\n documentGenerate.setPath(path);\n\n // Your .proto path: Set the import path of common_pb in Vue.\n documentGenerate.setProtoImportPath(\"../common_pb\");\n\n IoGameDocumentHelper.addDocumentGenerate(documentGenerate);\n }\n\n private static void generateCodeHtml() {\n var documentGenerate = new TypeScriptDocumentGenerate();\n\n // 设置代码生成所存放的路径，如果不做任何设置，将会生成在 target/code 目录中\n // By default, it will be generated in the target/code directory\n String path = rootPath + \"ioGameSdkTsExampleHtml/src/assets/gen/code\";\n documentGenerate.setPath(path);\n\n // Your .proto path: Set the import path of common_pb in Vue.\n documentGenerate.setProtoImportPath(\"../common_pb\");\n\n IoGameDocumentHelper.addDocumentGenerate(documentGenerate);\n }\n\n private static void generateCocosCreator() {\n var documentGenerate = new TypeScriptDocumentGenerate();\n\n // 设置代码生成所存放的路径，如果不做任何设置，将会生成在 target/code 目录中\n // By default, it will be generated in the target/code directory\n String path = rootPath + \"ioGameSdkTsExampleCocos/assets/scripts/gen/code\";\n documentGenerate.setPath(path);\n\n // Your .proto path: Set the import path of common_pb in CocosCreator\n documentGenerate.setProtoImportPath(\"db://assets/scripts/gen/common_pb\");\n\n IoGameDocumentHelper.addDocumentGenerate(documentGenerate);\n }\n\n private static void generateCodeAngular() {\n var documentGenerate = new TypeScriptDocumentGenerate();\n\n // 设置代码生成所存放的路径，如果不做任何设置，将会生成在 target/code 目录中\n // By default, it will be generated in the target/code directory\n String path = rootPath + \"ioGameSdkTsExampleAngular/src/assets/gen/code\";\n documentGenerate.setPath(path);\n\n // Your .proto path: Set the import path of common_pb in Vue.\n documentGenerate.setProtoImportPath(\"../common_pb\");\n\n IoGameDocumentHelper.addDocumentGenerate(documentGenerate);\n }\n}\n```\n\n\n\nAdvantages of SDK Code Generation\n1. Helps client-side developers reduce significant workload by eliminating the need to write a large amount of template code.\n2. Clear and semantically precise. The generated interaction code clearly defines parameter types and return types.\n3. Ensures parameter type safety and clarity in interface methods, effectively avoiding security risks and reducing basic errors during integration.\n4. Reduces communication costs between the server and client during integration; the code serves as documentation. The generated integration code includes documentation and usage examples, and the examples on the methods will guide you on how to use them, making it zero-learning-cost even for beginners.\n5. Helps client-side developers abstract away the interaction with the server, allowing them to focus more on the core business logic.\n6. Reduces the cognitive load during integration. The code is simple to use, similar to local method calls.\n7. Abandons the traditional protocol-based approach in favor of an interface-method-based integration approach.\n\n------\n\n\n\n\n### 2024-11-15 - v21.20\n\nhttps://github.com/iohao/ioGame/releases/tag/21.20\n\n**Version update summary**\n> 1. feat(GenerateDoc): Add DocumentMethod annotation : Action supports generating documentation method names through annotations.\n> 1. BroadcastDebug enhancements.\n> 1. feat(GenerateCode): #328 Added C# code generation CsharpDocumentGenerate, which can generate interactive code for Unity and Godot.\n\n\n------\n\n**feat(GenerateDoc):** Add DocumentMethod annotation : Action supports generating documentation method names through annotations.\n\nBy default, the method names in the generated action interaction code use the method names from the Java action. The action can add the `DocumentMethod` annotation to fix the method name, and when generating the integration code, ioGame will prioritize using the value of the `DocumentMethod` annotation.\n\n```java\n@ActionController(SdkCmd.cmd)\npublic final class SdkAction { \n @ActionMethod(SdkCmd.noReturn)\n @DocumentMethod(\"noReturnMethod\")\n public void noReturn(String name) {\n ... ...\n }\n}\n```\n\n---\n\n**feat(GenerateCode):** #328 Added C# code generation CsharpDocumentGenerate, which can generate interactive code for Unity and Godot.\n\n\n\nAbout examples\n\n1. see https://github.com/iohao/ioGameExamples/tree/main/SdkExample\n2. UnityExample: https://github.com/iohao/ioGameSdkCsharpExampleUnity\n3. GodotExample: https://github.com/iohao/ioGameSdkCsharpExampleGodot\n\n```java\npublic final class GenerateTest {\n // setting root path\n static String rootPath = \"/Users/join/gitme/ioGame-sdk/\";\n\n public static void main(String[] args) {\n // CHINA or US\n Locale.setDefault(Locale.CHINA);\n\n // Load the business framework of each gameLogicServer\n // 加载游戏逻辑服的业务框架\n yourListLogic().forEach(BrokerClientStartup::createBarSkeleton);\n\n /*\n * Generate actions, broadcasts, and error codes.\n * cn: 生成 action、广播、错误码\n */\n // About generating C# code\n generateCodeCsharpGodot();\n generateCodeCsharpUnity();\n\n // Added an enumeration error code class to generate error code related information\n IoGameDocumentHelper.addErrorCodeClass(YourGameCodeEnum.class);\n // Generate document\n IoGameDocumentHelper.generateDocument();\n }\n\n private static void generateCodeCsharpUnity() {\n var documentGenerate = new CsharpDocumentGenerate();\n // 设置代码生成所存放的路径，如果不做任何设置，将会生成在 target/code 目录中\n // By default, it will be generated in the target/code directory\n String path = rootPath + \"ioGameSdkCsharpExampleUnity/Assets/Scripts/Gen/Code\";\n documentGenerate.setPath(path);\n\n IoGameDocumentHelper.addDocumentGenerate(documentGenerate);\n }\n\n private static void generateCodeCsharpGodot() {\n var documentGenerate = new CsharpDocumentGenerate();\n // 设置代码生成所存放的路径，如果不做任何设置，将会生成在 target/code 目录中\n // By default, it will be generated in the target/code directory\n String path = rootPath + \"ioGameSdkCsharpExampleGodot/script/gen/code\";\n documentGenerate.setPath(path);\n\n IoGameDocumentHelper.addDocumentGenerate(documentGenerate);\n }\n}\n```\n\n\n\nAdvantages of SDK Code Generation\n1. Helps client-side developers reduce significant workload by eliminating the need to write a large amount of template code.\n2. Clear and semantically precise. The generated interaction code clearly defines parameter types and return types.\n3. Ensures parameter type safety and clarity in interface methods, effectively avoiding security risks and reducing basic errors during integration.\n4. Reduces communication costs between the server and client during integration; the code serves as documentation. The generated integration code includes documentation and usage examples, and the examples on the methods will guide you on how to use them, making it zero-learning-cost even for beginners.\n5. Helps client-side developers abstract away the interaction with the server, allowing them to focus more on the core business logic.\n6. Reduces the cognitive load during integration. The code is simple to use, similar to local method calls.\n7. Abandons the traditional protocol-based approach in favor of an interface-method-based integration approach.\n\n------\n\n**[other updates]**\n\n```xml\n3.25.5\n```\n\n---\n\n\n\n### 2024-10-28 - v21.19\n\nhttps://github.com/iohao/ioGame/releases/tag/21.19\n\n\n\n**版本更新汇总**\n\n> 1. [core] FlowContext provides the setUserId method to simplify the login operation.\n> 2. [broker] Added RingElementSelector load balancing implementation and set it as default to replace RandomElementSelector\n> 3. [core] [#386](https://github.com/iohao/ioGame/issues/386) Action supports constructor injection with parameters in Spring\n> 4. Simplify the implementation class of ActionParserListener related to ProtoDataCodec. and #386\n> 5. perf(i18n): 🐳 [#376](https://github.com/iohao/ioGame/issues/376) cmd check tips\n> 6. refactor(external): simplify and improve externalCache\n\n\n------\n\n**[core]** FlowContext provides the setUserId method to simplify the login operation.\n> FlowContext 提供登录方法以简化登录的使用\n\n```java\n@ActionController(LoginCmd.cmd)\npublic class TheLoginAction {\n ... ...\n\t@ActionMethod(LoginCmd.login)\n public UserInfo loginVerify(LoginVerify loginVerify, FlowContext flowContext) {\n long userId = ...;\n \n // Deprecated\n\t\tboolean success = UserIdSettingKit.settingUserId(flowContext, userId);\n // now\n boolean success = flowContext.setUserId(userId);\n\n return ...;\n }\n}\n```\n\n---\n\n**[core]** [#386](https://github.com/iohao/ioGame/issues/386) Action supports constructor injection with parameters in Spring\n> 在 Spring 中，Action 支持构造函数注入\n\n```java\n// Action supports constructor injection in Spring.\n@Component\n@AllArgsConstructor\n@ActionController(PersonCmd.cmd)\npublic class PersonAction { \n final PersonService personService;\n ...\n}\n```\n\n---\n\nrefactor(external): simplify and improve externalCache\n> 简化与提升游戏对外服缓存\n\n```java\n// create externalCache\nprivate static void extractedExternalCache() {\n // Deprecated\n DefaultExternalCmdCache externalCmdCache = new DefaultExternalCmdCache();\n // now\n var externalCmdCache = ExternalCmdCache.of();\n}\n```\n\n------\n\n**[其他更新]**\n\n```xml\n4.1.114.Final\n```\n\n------\n\n### 2024-10-09 - v21.18\n\nhttps://github.com/iohao/ioGame/releases/tag/21.18\n\n\n\n**版本更新汇总**\n\n> - [external] [#375](https://github.com/iohao/ioGame/issues/375) Support for lightweight or embedded Linux distributions. 支持轻量级或嵌入式 Linux 发行版。\n> - [core] [#376](https://github.com/iohao/ioGame/issues/376) Support i18n, such as logs and internal messages. 框架内的日志、内部消息支持 i18n。\n\n\n------\n\n**[core]**\n\n [#376](https://github.com/iohao/ioGame/issues/376) Support i18n, such as logs and internal messages. 框架内的日志、内部消息支持 i18n。\n\n```java\npublic class DemoApplication {\n public static void main(String[] args) {\n // setting defaultLocale, such as US or CHINA\n Locale.setDefault(Locale.US);\n Locale.setDefault(Locale.CHINA);\n\n ... start ioGame\n }\n}\n```\n\n------\n\n**[其他更新]**\n\n```\n2.6.17\n```\n\n------\n\n\n\n### 2024-09-25 - v21.17\n\nhttps://github.com/iohao/ioGame/releases/tag/21.17\n\n**版本更新汇总**\n\n> - [core] 简化 TraceIdSupplier 全链路调用日志跟踪默认实现\n> - [core] FlowContext 提供用户（玩家）所关联的用户线程执行器信息及虚拟线程执行器信息方法\n\n---\n\n**[core]**\n\nFlowContext 提供用户（玩家）所关联的用户线程执行器信息及虚拟线程执行器信息方法\n\n```java\nvoid testThreadExecutor(FlowContext flowContext) {\n // 获取 - 用户（玩家）所关联的用户线程执行器信息及虚拟线程执行器信息\n\n // 用户虚拟线程执行器信息\n ThreadExecutor virtualThreadExecutor = flowContext.getVirtualThreadExecutor();\n // 用户线程执行器信息\n ThreadExecutor threadExecutor = flowContext.getThreadExecutor();\n\n threadExecutor.execute(() -> {\n log.info(\"execute\");\n });\n\n threadExecutor.executeTry(() -> {\n log.info(\"executeTry\");\n });\n\n // get Executor\n Executor executor = threadExecutor.executor();\n}\n```\n\n------\n\n\n\n### 2024-09-09 - v21.16\n\nhttps://github.com/iohao/ioGame/releases/tag/21.16\n\n**版本更新汇总**\n\n> - [kit] [#291](https://github.com/iohao/ioGame/issues/291) 增加轻量可控的延时任务\n> - [kit] 细分时间日期相关工具。\n> - [Archive] [#363](https://github.com/iohao/ioGame/issues/363) light-redis-lock 相关模块\n> - [Archive] [#364](https://github.com/iohao/ioGame/issues/364) light-timer-task 相关模块\n> - [core] 增加同一个 ActionController 相同的 action 方法名只允许存在一个的检测。\n> - [core] Banner 增加启动时的错误数量提示。\n> - [core] [#365](https://github.com/iohao/ioGame/issues/365) 支持对接文档生成时，可以根据路由访问权限来控制文档的生成\n\n------\n\n**[kit]**\n\n[#291](https://github.com/iohao/ioGame/issues/291) 增加轻量可控的延时任务\n\n\n for example \n\n```java\n@Test\npublic void example() {\n long timeMillis = System.currentTimeMillis();\n\n DelayTask delayTask = DelayTaskKit.of(() -> {\n long value = System.currentTimeMillis() - timeMillis;\n log.info(\"1 - 最终 {} ms 后，执行延时任务\", value);\n })\n .plusTime(Duration.ofSeconds(1)) // 增加 1 秒的延时 \n .task(); // 启动任务\n\n delayTask.plusTimeMillis(500); // 增加 0.5 秒的延时\n delayTask.minusTimeMillis(500);// 减少 0.5 秒的延时时间\n\n // 因为 taskId 相同，所以会覆盖之前的延时任务\n String taskId = delayTask.getTaskId();\n delayTask = DelayTaskKit.of(taskId, () -> {\n long value = System.currentTimeMillis() - timeMillis;\n log.info(\"2 - 最终 {} ms 后，执行延时任务\", value);\n })\n .plusTime(Duration.ofSeconds(1)) // 增加 1 秒的延时\n .task(); // 启动任务\n\n // 取消延时任务，下面两个方法是等价的\n delayTask.cancel();\n DelayTaskKit.cancel(taskId);\n\n // 可以通过 taskId 查找该延时任务\n Optional optionalDelayTask = DelayTaskKit.optional(taskId);\n if (optionalDelayTask.isPresent()) {\n var delayTask = optionalDelayTask.get();\n }\n\n // 通过 taskId 查找延时任务，存在则执行给定逻辑\n DelayTaskKit.ifPresent(taskId, delayTask -> {\n delayTask.plusTimeMillis(500); // 增加 0.5 秒的延时时间\n });\n}\n```\n\n------\n\n细分时间日期相关工具。\n\nsee com.iohao.game.common.kit.time\n\n------\n\n**[Archive]**\n\n[#363](https://github.com/iohao/ioGame/issues/363) light-redis-lock 相关模块\n\n将 light-redis-lock、light-redis-lock-spring-boot-starter 模块做归档。在过去的时间里，由于一直没有改动这些模块的相关内容，现决定将不再上传到 maven 库中，以节约公共资源。如果你使用了该模块的相关内容，请指定最后一个版本即可。如\n\n```xml\n\n\n com.iohao.game\n light-redis-lock\n 21.15\n\n\n\n\n com.iohao.game\n light-redis-lock-spring-boot-starter\n 21.15\n\n```\n\n\n\n\n------\n\n[#364](https://github.com/iohao/ioGame/issues/364) light-timer-task 相关模块\n\n将 light-timer-task 模块做归档。在过去的时间里，由于一直没有改动这些模块的相关内容；同时，也因为框架内置了类似的功能 #291 。现决定将不再上传到 maven 库中，以节约公共资源。如果你使用了该模块的相关内容，请指定最后一个版本即可。如\n\n```xml\n\n\n com.iohao.game\n light-timer-task\n 21.15\n\n```\n\n\n\n------\n\n**[core]**\n\n[#365](https://github.com/iohao/ioGame/issues/365) 支持对接文档生成时，可以根据路由访问权限来控制文档的生成\n\n\n\n生成相关代码的使用及相关文档\n\n- `ExternalGlobalConfig.accessAuthenticationHook`，相关文档路由访问权限控制\n- IoGameDocumentHelper，相关文档游戏对接文档生成\n\nfor example \n\n```java\npublic class MyExternalServer {\n public static void extractedAccess() {\n // https://iohao.github.io/game/docs/external/access_authentication\n var accessAuthenticationHook = ExternalGlobalConfig.accessAuthenticationHook;\n ... 省略部分代码\n // 添加 - 拒绝玩家访问权限的控制\n accessAuthenticationHook.addRejectionCmd(RankCmd.cmd, RankCmd.internalUpdate);\n }\n}\n\npublic class TestGenerate {\n ... 省略部分代码\n public static void main(String[] args) {\n // 对外服访问权限控制\n MyExternalServer.extractedAccess();\n // （复用）设置文档路由访问权限控制\n IoGameDocumentHelper.setDocumentAccessAuthentication(ExternalGlobalConfig.accessAuthenticationHook::reject);\n \n // ====== 生成对接文档、生成 proto ======\n// generateCsharp();\n// generateTypeScript();\n // 生成文档\n IoGameDocumentHelper.generateDocument();\n // .proto 文件生成\n// generateProtoFile();\n }\n}\n```\n\n\n\n**预览 - 没有做控制前的生成**\n\n```latex\n==================== RankAction ====================\n路由: 4 - 1 --- 【listRank】 --- 【RankAction:48】【listRank】\n 方法参数: StringValue 排行类型\n 方法返回值: ByteValueList 玩家排行名次更新\n \n路由: 4 - 10 --- 【玩家排行名次更新】 --- 【RankAction:60】【internalUpdate】\n 方法参数: RankUpdate 玩家排行名次更新\n 方法返回值: void \n```\n\n**预览 - 加入了访问控制后的生成**\n\n我们可以看见，路由为 4-10 的 action 方法没有生成到对接文档中。\n\n```latex\n==================== RankAction ====================\n路由: 4 - 1 --- 【listRank】 --- 【RankAction:48】【listRank】\n 方法参数: StringValue 排行类型\n 方法返回值: ByteValueList 玩家排行名次更新\n```\n\n\n\n提示：除了文档文档的访问权限控制外，还支持 SDK TypeScript、SDK C# ...等客户端代码生成的访问权限控制。\n\n\n\n\n------\n\n**[其他更新]**\n\n```xml\n4.1.113.Final\n```\n\n------\n\n\n\n### 2024-08-26 - v21.15\n\nhttps://github.com/iohao/ioGame/releases/tag/21.15\n\n\n\n**版本更新汇总**\n\n> - [core] [#351](https://github.com/iohao/ioGame/issues/351) 增加 UserProcessor 线程执行器的选择策略扩展\n> - [core] [#350](https://github.com/iohao/ioGame/issues/350) 修复请求消息在 Broker 环节乱序的问题\n> - [core] [#353](https://github.com/iohao/ioGame/issues/353) 对接文档支持框架内置错误码的生成\n> - [core] [#354](https://github.com/iohao/ioGame/issues/354) 日志打印调整\n> - [core] [#359](https://github.com/iohao/ioGame/issues/359) [逻辑服-监听] 增加打印其他进程逻辑服的上线与下线信息\n> - [core] 优化 ThreadExecutorRegion 相关实现类。\n> - [external] UserSession 接口新增 ofRequestMessage 方法，简化玩家在游戏对外服中创建请求对象。\n\n------\n\n**[external]**\n\nUserSession 接口新增 ofRequestMessage 方法，简化玩家在游戏对外服中创建请求对象。 for example\n\n```java\nvar cmdInfo = CmdInfo.of(1, 1);\nRequestMessage request = userSession.ofRequestMessage(cmdInfo);\n```\n\n------\n\n**[core]**\n\n[#359](https://github.com/iohao/ioGame/issues/359) [逻辑服-监听] 增加打印其他进程逻辑服的上线与下线信息\n\n```java\npublic class MyLogicServer extends AbstractBrokerClientStartup {\n ...\n\n @Override\n public BrokerClientBuilder createBrokerClientBuilder() {\n BrokerClientBuilder builder = BrokerClient.newBuilder();\n ...\n // 添加监听 - 打印其他进程逻辑服的上线与下线信息\n builder.addListener(SimplePrintBrokerClientListener.me());\n return builder;\n }\n}\n```\n\n------\n\n[#351](https://github.com/iohao/ioGame/issues/351) 增加 UserProcessor 线程执行器的选择策略扩展\n\n> for example，注意事项：当你的 UserProcessor 做了线程执行器的选择策略扩展，需要重写 CustomSerializer 接口的相关方法。\n\n```java\n// 为请求消息开启有序的、多线程处理的优化\nIoGameGlobalConfig.enableUserProcessorExecutorSelector();\n```\n\n\n\n------\n\n### 2024-08-08 - v21.14\n\nhttps://github.com/iohao/ioGame/releases/tag/21.14\n\n\n\n**版本更新汇总**\n\n> - [code quality] 提升代码质量，see [ioGame - Qodana Cloud](https://qodana.cloud/organizations/3k6Pm/teams/zxRGm)\n> - [javadoc] 增强相关模块的 javadoc ：业务框架、压测与模拟客户端请求、领域事件、Room\n> - [core] [#346](https://github.com/iohao/ioGame/issues/346) 业务框架 InOutManager 提供扩展点\n> - [core] [#344](https://github.com/iohao/ioGame/issues/344) 登录时，如果 FlowContext 存在 userId 就不请求游戏对外服\n> - [broker] fixed [#342](https://github.com/iohao/ioGame/issues/342) 非集群环境下，Broker 断开重启后，逻辑服没有将其重新加入到 BrokerClientManager 中所引发的 NPE。\n\n------\n\n**[core]**\n\n [#346](https://github.com/iohao/ioGame/issues/346) **业务框架 InOutManager 提供扩展点**\n\n在构建器中配置 InOutManager 策略，框架内置了两个实现类，分别是\n\n1. ofAbcAbc ：in ABC，out ABC 的顺序，即编排时的顺序。\n2. ofPipeline：in ABC，out CBA 的顺序，类似的 netty Pipeline 。（默认策略，如果不做任何设置，将使用该策略）\n\n\n\nfor example 在构建器中配置 InOutManager 策略\n\n```java\npublic void config() {\n BarSkeletonBuilder builder = ...;\n builder.setInOutManager(InOutManager.ofAbcAbc());\n builder.setInOutManager(InOutManager.ofPipeline());\n}\n```\n\n\n\n------\n\n\n\n### 2024-07-24 - v21.13\n\nhttps://github.com/iohao/ioGame/releases/tag/21.13\n\n\n\n**版本更新汇总**\n\n- [external] [#334](https://github.com/iohao/ioGame/issues/334) 顶号操作 bug，有概率触发并发问题\n- [core] FlowContext 新增 createRequestCollectExternalMessage 方法\n- [javadoc] 源码 javadoc 增强\n\n------\n\n\n\n**[core]**\n\nFlowContext 新增 createRequestCollectExternalMessage 方法，request 与游戏对外服交互。\n\n```java\n... ... 省略部分代码\n@ActionMethod(ExternalBizRegionCmd.listOnlineUserAll)\npublic List listOnlineUserAll(FlowContext flowContext) {\n\n // 创建 RequestCollectExternalMessage\n var request = flowContext\n .createRequestCollectExternalMessage(MyExternalBizCode.onlineUser);\n\n // 访问多个【游戏对外服】\n var collectExternalMessage = flowContext\n .invokeExternalModuleCollectMessage(request);\n\n return listUserId(collectExternalMessage);\n}\n```\n\n------\n\n\n\n**[其他更新]**\n\n```xml\n4.1.112.Final\n1.18.34\n```\n\n------\n\n\n\n### 2024-07-08 - v21.12\n\nhttps://github.com/iohao/ioGame/releases/tag/21.12\n\n\n\n**版本更新汇总**\n\n- [light-game-room] [#326](https://github.com/iohao/ioGame/issues/326) GameFlowContext getRoom、getPlayer 方法返回值改成泛型\n- [对接文档] [#330](https://github.com/iohao/ioGame/issues/330) 增强，支持对接文档生成与扩展，包括文本文档生成、联调代码生成 ...等\n\n\n\n当前版本，为之后生成联调代码做了充分的准备\n\n------\n\n\n\n**[light-game-room]**\n\n[#326](https://github.com/iohao/ioGame/issues/326) GameFlowContext getRoom、getPlayer 方法返回值改成泛型\n\n```java\nGameFlowContext gameFlowContext = ...;\n// FightRoomEntity 是自定义的 Room 对象\n\n// Room、Player 在使用时，不需要强制转换了\nFightRoomEntity room = gameFlowContext.getRoom();\nFightPlayerEntity player = gameFlowContext.getPlayer();\n```\n\n------\n\n\n\n**[对接文档]** \n\n[#330](https://github.com/iohao/ioGame/issues/330) 增强，支持对接文档生成与扩展，包括文本文档生成、联调代码生成 ...等。开发者做更多个性化的扩展\n\n\n\n在该版本中，我们已经新做了对接文档相关模块；该版本功能更加的强大，使用上也更加的简洁。新版本的对接文档模块，除了能提供文本文档的生成外，还能支持生成与客户端联调的代码、并且是可扩展的。通常，客户端联调代码有：\n\n1. 支持生成 C# 客户端的联调代码，通常用在 Unity、Godot 客户端\n2. 支持生成 TypeScript 客户端的联调代码，通常用在 cocos、laya 客户端\n\n\n\n```java\npublic static void main(String[] args) {\n // 添加枚举错误码 class，用于生成错误码相关信息\n IoGameDocumentHelper.addErrorCodeClass(GameCode.class);\n\n // 添加文档生成器，文本文档\n IoGameDocumentHelper.addDocumentGenerate(new TextDocumentGenerate());\n // 添加文档生成器，Ts 联调代码生成\n IoGameDocumentHelper.addDocumentGenerate(new TypeScriptDocumentGenerate());\n // 生成文档\n IoGameDocumentHelper.generateDocument();\n}\n```\n\n上述代码\n\n- 添加了错误码的生成\n- 添加了文本文档的生成\n- 添加了 Ts 客户端联调代码的生成（包括 action、广播、错误码...相关代码的生成）， [SDK TypeScript 客户端代码生成；方便 CocosCeator、或其他支持 TypeScript 的客户端对接。 #329](https://github.com/iohao/ioGame/issues/329)\n\n\n\naddDocumentGenerate 是可扩展的，这将意味着开发者可以扩展出 C#、GodotScript、Js ...等不同客户端的联调代码。默认，我们提供了一个文本文档，即 TextDocumentGenerate，如果默认的实现满足不了当下需求，开发者也可以定制个性化的文档，如 json 格式的。\n\n\n\n\n\n\n**新增 DocumentGenerate 接口**\n\n开发者可利用该接口进行定制个性化的对接文档，如代码生成 ...等。\n\n```java\n/**\n * 对接文档生成接口，可扩展不同的实现\n */\npublic interface DocumentGenerate {\n /**\n * 生成文档\n *\n * @param ioGameDocument ioGameDocument\n */\n void generate(IoGameDocument ioGameDocument);\n}\n\n/**\n * 文档相关信息，如 action 相关、广播相关、错误码相关。\n */\n@Getter\npublic final class IoGameDocument {\n /** 已经解析好的广播文档 */\n List broadcastDocumentList;\n /** 已经解析好的错误码文档 */\n List errorCodeDocumentList;\n /** 已经解析好的 action 文档 */\n List actionDocList;\n}\n```\n\n\n\n开发者可以通过实现 DocumentGenerate 接口来扩展不同的文档生成，开发者可以扩展此接口来定制更多个性化的扩展，如\n\n- html 版本的文档。\n- json 版本的文档。\n- 其他语言的联调文档 ...等。\n\n\n\n```java\n// 使用示例\nprivate static void test() {\n var documentGenerate = new YourDocumentGenerate();\n IoGameDocumentHelper.addDocumentGenerate(documentGenerate);\n}\n```\n\n\n\n------\n\n其他：废弃旧版本对接文档相关类 DocActionSend、DocActionSends、ActionDocs、ActionSendDoc、ActionSendDocs、ActionSendDocsRegion、BarSkeletonDoc、BroadcastDoc、BroadcastDocBuilder、ErrorCodeDocs、ErrorCodeDocsRegion。\n\n------\n\n21.10 及之前版本的使用示例（对接文档）\n\n```java\npublic static void main(String[] args) {\n ... 省略部分代码\n\n new NettyRunOne()\n ... ...\n .startup();\n\n // 生成对接文档\n BarSkeletonDoc.me().buildDoc();\n}\n```\n\n------\n\n\n\n### 2024-06-21 - v21.10\n\n（问题版本）\n\nhttps://github.com/iohao/ioGame/releases/tag/21.10\n\n------\n\n**版本更新汇总**\n\n- [core] [#315](https://github.com/iohao/ioGame/issues/315) ResponseMessage 增加协议碎片便捷获取，简化跨服调用时的使用\n- [core] ActionCommand 增加 containAnnotation、getAnnotation 方法，简化获取 action 相关注解信息的使用。\n- [kit] [动态属性] 增加 ifNull 方法，如果动态属性值为 null，则执行给定的操作，否则不执行任何操作。执行给定操作后将得到一个返回值，该返回值会设置到动态属性中。\n- [kit] TimeKit 增加 nowLocalDate 方法，可减少 LocalDate 对象的创建；优化 currentTimeMillis 方法的时间更新策略。同时，优化 nowLocalDate、currentTimeMillis 方法，不使用时将不会占用相关资源。\n- [EventBus] 分布式事件总线增加 EventBusRunner 接口。EventBus 接口化，方便开发者自定义扩展。fix 订阅者使用自身所关联的 EventBus 处理相关事件。\n\n------\n\n**[core]** [315](https://github.com/iohao/ioGame/issues/315) ResponseMessage 增加协议碎片便捷获取，简化跨服调用时的使用\n\n框架具备协议碎片特性。某些业务中，我们需要跨服访问其他游戏逻辑服，以获取某些业务数据；一些简单的数据，我们可以通过协议碎片来返回，从而避免定义过多的协议。\n\n\n\n现为 ResponseMessage 增加协议碎片支持，简化跨服调用时的使用，新增的方法如下\n\n```java\npublic void test() {\n ResponseMessage responseMessage = ...;\n\n // object\n responseMessage.getValue(Student.class);\n List listValue = responseMessage.listValue(Student.class);\n\n // int\n int intValue = responseMessage.getInt();\n List listInt = responseMessage.listInt();\n\n // long\n long longValue = responseMessage.getLong();\n List listLong = responseMessage.listLong();\n\n // String\n String stringValue = responseMessage.getString();\n List listString = responseMessage.listString();\n\n // boolean\n boolean boolValue = responseMessage.getBoolean();\n List listBoolean = responseMessage.listBoolean();\n}\n```\n\n\n\n示例说明\n\n- HomeAction 是 【Home 游戏逻辑服】提供的 action\n- UserAction 是 【User 游戏逻辑服】提供的 action\n\n两个逻辑服的交互如下，UserAction 使用跨服方式调用了【Home 游戏逻辑服】的几个方法，并通过 responseMessage 的协议碎片支持，简化跨服调用时的使用。\n\n\n\n示例中演示了 string、string list、object list 的简化使用（协议碎片获取时的简化使用）。\n\n```java\n@ProtobufClass\n@FieldDefaults(level = AccessLevel.PUBLIC)\npublic class Student {\n String name;\n}\n\n// home 游戏逻辑服提供的 action\npublic class HomeAction {\n @ActionMethod(HomeCmd.name)\n public String name() {\n return \"a\";\n }\n\n @ActionMethod(HomeCmd.listName)\n public List listName() {\n return List.of(\"a\", \"b\");\n }\n\n @ActionMethod(HomeCmd.listStudent)\n public List listStudent() {\n Student student = new Student();\n student.name = \"a\";\n\n Student student2 = new Student();\n student2.name = \"b\";\n\n return List.of(student, student2);\n }\n}\n\n@ActionController(UserCmd.cmd)\npublic class UserAction {\n @ActionMethod(UserCmd.userSleep)\n public void userSleep(FlowContext flowContext) {\n\n flowContext.invokeModuleMessageAsync(HomeCmd.of(HomeCmd.name), responseMessage -> {\n String name = responseMessage.getString();\n log.info(\"{}\", name);\n });\n\n flowContext.invokeModuleMessageAsync(HomeCmd.of(HomeCmd.listName), responseMessage -> {\n var listName = responseMessage.listString();\n log.info(\"{}\", listName);\n });\n\n flowContext.invokeModuleMessageAsync(HomeCmd.of(HomeCmd.listStudent), responseMessage -> {\n List studentList = responseMessage.listValue(Student.class);\n log.info(\"{}\", studentList);\n });\n }\n}\n```\n\n\n\n------\n\n**[core]** ActionCommand 增加 containAnnotation、getAnnotation 方法，简化获取 action 相关注解信息的使用。\n\n```java\nActionCommand actionCommand = flowContext.getActionCommand();\n\nbool contain = actionCommand.containAnnotation(DisableDebugInout.class);\nvar annotation = actionCommand.getAnnotation(DisableDebugInout.class);\n```\n\n\n\n------\n\n**[EventBus] 分布式事件总线**\n\n1. [增强扩展] 将抽象类 AbstractEventBusRunner 标记为过时的，由接口 EventBusRunner 代替。\n2. [增强扩展] 分布式事件总线 EventBus 接口化，方便开发者自定义扩展。增加[总线相关的 javadoc](https://iohao.github.io/javadoc/com/iohao/game/action/skeleton/eventbus/package-summary.html)。\n3. [fix] 订阅者使用自身所关联的 EventBus 处理相关事件。\n\n\n\n关于 fix 订阅者使用自身所关联的 EventBus 处理相关事件，在此之前可能引发 bug 的场景如下\n\n1. 【游戏逻辑服 A】 发布事件。\n2. 【游戏逻辑服 B】 订阅者接收事件并处理，在处理过程中又调用了【游戏逻辑服 A】 某个 action 方法。\n\n\n\n该业务场景，会在多服单进程下会引发调用超时，但在多服多进程下则不会超时。\n\n\n\n------\n\n**[kit] TimeKit**\n\n增强 TimeKit 增加 nowLocalDate 方法，可减少 LocalDate 对象的创建；\n\n优化 currentTimeMillis 方法的时间更新策略。\n\n优化 nowLocalDate、currentTimeMillis 不使用时将不会占用相关资源。\n\n```csharp\n@Test\npublic void test() {\n long millis = TimeKit.currentTimeMillis();\n Assert.assertTrue(millis > 0);\n\n LocalDate localDate = TimeKit.nowLocalDate();\n Assert.assertTrue(localDate.isEqual(LocalDate.now()));\n}\n```\n\n\n\n------\n\n**[kit] 动态属性**\n\n[动态属性] 增加 ifNull 方法，如果动态属性值为 null，则执行给定的操作，否则不执行任何操作。执行给定操作后将得到一个返回值，该返回值会设置到动态属性中。\n\n```csharp\npublic class AttrOptionDynamicTest {\n // 动态属性 key\n AttrOption attrCatOption = AttrOption.valueOf(\"AttrCat\");\n\n @Test\n public void ifNull() {\n var myAttrOptions = new MyAttrOptions();\n Assert.assertNull(myAttrOptions.option(attrCatOption));\n\n // 如果 catAttrOption 属性为 null，则创建 AttrCat 对象，并赋值到属性中\n myAttrOptions.ifNull(attrCatOption, AttrCat::new);\n Assert.assertNotNull(myAttrOptions.option(attrCatOption));\n }\n\n private static class AttrCat {\n String name;\n }\n\n @Getter\n private static class MyAttrOptions implements AttrOptionDynamic {\n final AttrOptions options = new AttrOptions();\n }\n}\n```\n\n\n\n------\n\n**[其他 - 相关库升级]**\n\n4.1.111.Final\n\n4.0.5\n\n2.4.23\n\n---\n\n\n\n### 2024-06-03 - v21.9\n\n（问题版本）\n\nhttps://github.com/iohao/ioGame/releases/tag/21.9\n\n\n---\n\n**版本更新汇总**\n\n- [core] [#294](https://github.com/iohao/ioGame/issues/294) 增加范围内的广播接口 RangeBroadcaster，业务参数支持基础类型的简化使用\n- [core-对接文档] [#293](https://github.com/iohao/ioGame/issues/293) 广播文档构建器支持对参数的单独描述\n- [light-game-room] [#297](https://github.com/iohao/ioGame/issues/297) 模拟系统创建房间，RoomCreateContext 的使用\n- [light-game-room] [#298](https://github.com/iohao/ioGame/issues/298) 模拟系统创建房间，GameFlowContext 的使用\n- [core] [#301](https://github.com/iohao/ioGame/issues/301) FlowContext 更新元信息后，需要立即生效（跨服调用时）\n- [内置 kit] 开放 TaskListener 接口\n- 为 SimpleRoom aggregationContext 属性提供默认值，移除 RoomCreateContext 接口的 getAggregationContext 方法，以免产生误导。\n\n\n---\n\n\n\n**[light-game-room]**\n\n为 SimpleRoom aggregationContext 属性提供默认值\n\n \n\n[#297](https://github.com/iohao/ioGame/issues/297)，模拟系统创建房间，RoomCreateContext 的使用\n\n> 移除 RoomCreateContext 接口的 getAggregationContext 方法，以免产生误导。\n>\n> RoomCreateContext 增加默认重载\n\n```java\nRoomCreateContext.of(); // 无房间创建者，通常表示系统创建\nRoomCreateContext.of(userId); // 房间创建者为 userId\n```\n\n \n\n [#298](https://github.com/iohao/ioGame/issues/298) 模拟系统创建房间，GameFlowContext 的使用\n\n```java\npublic void test() {\n Room room = ...;\n GameFlowContext context = GameFlowContext.of(room);\n ... 省略部分代码\n}\n```\n\n---\n\n**[core]**\n\n[#294](https://github.com/iohao/ioGame/issues/294) 增加范围内的广播接口 RangeBroadcaster，业务参数支持基础类型的简化使用\n\n```java\npublic void testRangeBroadcaster(FlowContext flowContext) {\n // ------------ object ------------\n // 广播 object\n DemoBroadcastMessage message = new DemoBroadcastMessage();\n message.msg = \"helloBroadcast --- 1\";\n RangeBroadcaster.of(flowContext)\n .setResponseMessage(cmdInfo, message);\n // 广播 object list\n List messageList = List.of(message);\n RangeBroadcaster.of(flowContext)\n .setResponseMessageList(cmdInfo, messageList);\n\n // ------------ int ------------\n // 广播 int\n int intValue = 1;\n RangeBroadcaster.of(flowContext)\n .setResponseMessage(cmdInfo, intValue);\n // 广播 int list\n List intValueList = List.of(1, 2);\n RangeBroadcaster.of(flowContext)\n .setResponseMessageIntList(cmdInfo, intValueList);\n\n // ------------ long ------------\n // 广播 long\n long longValue = 1L;\n RangeBroadcaster.of(flowContext)\n .setResponseMessage(cmdInfo, longValue);\n // 广播 long list\n List longValueList = List.of(1L, 2L);\n RangeBroadcaster.of(flowContext)\n .setResponseMessageLongList(cmdInfo, longValueList);\n\n // ------------ String ------------\n // 广播 String\n String stringValue = \"1\";\n RangeBroadcaster.of(flowContext)\n .setResponseMessage(cmdInfo, stringValue);\n // 广播 String list\n List stringValueList = List.of(\"1L\", \"2L\");\n RangeBroadcaster.of(flowContext)\n .setResponseMessageStringList(cmdInfo, stringValueList);\n \n // ------------ boolean ------------\n // 广播 boolean\n boolean boolValue = true;\n RangeBroadcaster.of(flowContext)\n .setResponseMessage(cmdInfo, boolValue);\n // 广播 boolean list\n List boolValueList = List.of(true, false);\n RangeBroadcaster.of(flowContext)\n .setResponseMessageBoolList(cmdInfo, boolValueList);\n}\n```\n\n \n\n[#301](https://github.com/iohao/ioGame/issues/301) FlowContext 更新元信息后，需要立即生效（跨服调用时）\n\n> 在此之前，更新元信息后，并不会将元信息同步到 FlowContext 中，只会将元信息同步到游戏对外服中；所以在更新元信息后，紧接着执行跨服调用是不能获取新的元信息内容的。\n>\n> 当前 issues 会对这部分做增强，也就是在更新元信息后，会将元信息同步到 FlowContext 中；这样，在后续的跨服调用中也能获取到最新的元信息。\n\n```java\nvoid test1(FlowContext flowContext) {\n // 获取元信息\n MyAttachment attachment = flowContext.getAttachment(MyAttachment.class);\n attachment.nickname = \"渔民小镇\";\n\n // [同步]更新 - 将元信息同步到玩家所在的游戏对外服中\n flowContext.updateAttachment(attachment);\n\n // 跨服请求\n CmdInfo helloCmdInfo = CmdInfo.of(1, 1);\n flowContext.invokeModuleMessage(helloCmdInfo);\n}\n\n@ActionController(1)\npublic class DemoFightAction {\n @ActionMethod(1)\n void hello(FlowContext flowContext) {\n // 可以得到最新的元信息\n MyAttachment attachment = flowContext.getAttachment(MyAttachment.class);\n log.info(\"{}\", attachment.nickname);\n }\n}\n```\n\n \n\n [#293](https://github.com/iohao/ioGame/issues/293) 广播文档构建器支持对参数的单独描述\n\n```java\n private void extractedDco(BarSkeletonBuilder builder) {\n // UserCmd\n builder.addBroadcastDoc(BroadcastDoc.newBuilder(UserCmd.of(UserCmd.enterSquare))\n .setDataClass(SquarePlayer.class)\n .setDescription(\"新玩家加入房间，给房间内的其他玩家广播\")\n ).addBroadcastDoc(BroadcastDoc.newBuilder(UserCmd.of(UserCmd.offline))\n .setDataClass(LongValue.class, \"userId\")\n .setDescription(\"有玩家下线了\")\n );\n}\n```\n\n> 下面是生成后的对接文档预览\n\n```text\n==================== FightHallAction 大厅（类似地图） ====================\n \n路由: 1 - 2 --- 【进入大厅】 --- 【FightHallAction:94】【enterSquare】\n 方法参数: EnterSquare enterSquare 进入大厅\n 方法返回值: ByteValueList 所有玩家\n 广播推送: SquarePlayer ，(新玩家加入房间，给房间内的其他玩家广播)\n \n\n路由: 1 - 5 --- 【玩家下线】 --- 【FightHallAction:154】【offline】\n 方法返回值: void \n 广播推送: LongValue userId，(有玩家下线了)\n\n```\n\n\n\n**[内置 kit]** \n\n开放 TaskListener 接口，TaskListener 是 TaskKit 相关的任务监听接口。\n\n\n\nTaskListener 任务监听回调，使用场景有：一次性延时任务、任务调度、轻量可控的延时任务、轻量的定时入库辅助功能 ...等其他扩展场景。这些使用场景都有一个共同特点，即监听回调。接口提供了 4 个方法，如下\n\n1. CommonTaskListener.onUpdate()，监听回调\n2. CommonTaskListener.triggerUpdate()，是否触发 CommonTaskListener.onUpdate() 监听回调方法\n3. CommonTaskListener.onException(Throwable) ，异常回调。在执行 CommonTaskListener.triggerUpdate() 和 CommonTaskListener.onUpdate() 方法时，如果触发了异常，异常将被该方法捕获。\n4. CommonTaskListener.getExecutor()，指定执行器来执行上述方法，目的是不占用业务线程。\n\n\n\n\n---\n\n\n\n### 2024-05-19 - v21.8\n\nhttps://github.com/iohao/ioGame/releases/tag/21.8\n\n\n---\n\n**版本更新汇总**\n\n- [light-game-room] [#278](https://github.com/iohao/ioGame/issues/278) 桌游类、房间类游戏的扩展模块，简化与规范化房间管理相关的、开始游戏流程相关的、玩法操作相关的相关扩展\n- [core] [#290](https://github.com/iohao/ioGame/issues/290) 新增广播文档构建器，简化生成广播对接文档\n- [示例集合整理] 将 SimpleExample、SpringBootExample、ioGameWeb2Game、fxglSimpleGame FXGL + netty合并成一个示例项目。\n\n---\n\n\n\n**[core]** \n\n[#290](https://github.com/iohao/ioGame/issues/290) 新增广播文档构建器，简化生成广播对接文档\n\n下面是使用示例\n\n```java\npublic class MyLogicServer extends AbstractBrokerClientStartup {\n @Override\n public BarSkeleton createBarSkeleton() {\n // 业务框架构建器\n BarSkeletonBuilder builder = ...\n \n // 错误码、广播、推送对接文档生成\n extractedDco(builder);\n\n return builder.build();\n }\n \n private void extractedDco(BarSkeletonBuilder builder) {\n // 错误码\n Arrays.stream(GameCode.values()).forEach(builder::addMsgExceptionInfo);\n\n // UserCmd\n builder.addBroadcastDoc(BroadcastDoc.newBuilder(UserCmd.of(UserCmd.enterSquare))\n .setDataClass(SquarePlayer.class)\n .setDescription(\"新玩家加入房间，给房间内的其他玩家广播\")\n ).addBroadcastDoc(BroadcastDoc.newBuilder(UserCmd.of(UserCmd.move))\n .setDataClass(SquarePlayerMove.class)\n .setDescription(\"其他玩家的移动\")\n ).addBroadcastDoc(BroadcastDoc.newBuilder(UserCmd.of(UserCmd.offline))\n .setDataClass(LongValue.class)\n .setDescription(\"有玩家下线了。userId\")\n );\n\n // room\n builder.addBroadcastDoc(BroadcastDoc.newBuilder(RoomCmd.of(RoomCmd.roomUpdateBroadcast))\n .setDataClass(FightRoomNotice.class)\n .setDescription(\"房间更新通知\")\n ).addBroadcastDoc(BroadcastDoc.newBuilder(RoomCmd.of(RoomCmd.playerEnterRoomBroadcast))\n .setDataClass(FightPlayer.class)\n .setDescription(\"有新玩家加入房间\")\n ).addBroadcastDoc(BroadcastDoc.newBuilder(RoomCmd.of(RoomCmd.enterRoom))\n .setDataClass(FightEnterRoom.class)\n .setDescription(\"玩家自己进入房间\")\n ).addBroadcastDoc(BroadcastDoc.newBuilder(RoomCmd.of(RoomCmd.dissolveRoomBroadcast))\n .setDescription(\"解散房间\")\n ).addBroadcastDoc(BroadcastDoc.newBuilder(RoomCmd.of(RoomCmd.quitRoom))\n .setDataClass(LongValue.class)\n .setDescription(\"有玩家退出房间了。userId\")\n ).addBroadcastDoc(BroadcastDoc.newBuilder(RoomCmd.of(RoomCmd.ready))\n .setDataClass(PlayerReady.class)\n .setDescription(\"有玩家准备或取消准备了\")\n ).addBroadcastDoc(BroadcastDoc.newBuilder(RoomCmd.of(RoomCmd.nextRoundBroadcast))\n .setDataClass(IntValue.class)\n .setDescription(\"对局开始，通知玩家开始选择。round 当前对局数\")\n ).addBroadcastDoc(BroadcastDoc.newBuilder(RoomCmd.of(RoomCmd.operationBroadcast))\n .setDataClass(LongValue.class)\n .setDescription(\"通知其他玩家，有玩家做了选择。userId\")\n ).addBroadcastDoc(BroadcastDoc.newBuilder(RoomCmd.of(RoomCmd.littleSettleBroadcast))\n .setDataClassList(FightRoundPlayerScore.class)\n .setDescription(\"广播玩家对局分数\")\n ).addBroadcastDoc(BroadcastDoc.newBuilder(RoomCmd.of(RoomCmd.gameOverBroadcast))\n .setDescription(\"游戏结束\")\n );\n }\n}\n```\n\n下面是生成后的对接文档预览\n\n```text\n\n==================== FightHallAction 大厅（类似地图） ====================\n路由: 1 - 1 --- 【登录】 --- 【FightHallAction:67】【loginVerify】\n 方法参数: LoginVerify loginVerify 登录验证\n 方法返回值: UserInfo 玩家信息\n \n路由: 1 - 2 --- 【进入大厅】 --- 【FightHallAction:95】【enterSquare】\n 方法参数: EnterSquare enterSquare 进入大厅\n 方法返回值: ByteValueList 所有玩家\n 广播推送: SquarePlayer 新玩家加入房间，给房间内的其他玩家广播\n \n路由: 1 - 4 --- 【玩家移动】 --- 【FightHallAction:131】【move】\n 方法参数: SquarePlayerMove squarePlayerMove 玩家移动\n 方法返回值: void \n 广播推送: SquarePlayerMove 其他玩家的移动\n \n路由: 1 - 5 --- 【玩家下线】 --- 【FightHallAction:155】【offline】\n 方法返回值: void \n 广播推送: LongValue 有玩家下线了。userId\n \n\n==================== FightRoomAction ====================\n路由: 2 - 1 --- 【玩家创建新房间】 --- 【FightRoomAction:63】【createRoom】\n 方法返回值: void \n \n路由: 2 - 2 --- 【玩家进入房间】 --- 【FightRoomAction:96】【enterRoom】\n 方法参数: LongValue roomId 房间号\n 方法返回值: void 房间信息\n 广播推送: FightEnterRoom 玩家自己进入房间\n \n路由: 2 - 3 --- 【玩家退出房间】 --- 【FightRoomAction:120】【quitRoom】\n 方法返回值: void \n 广播推送: LongValue 有玩家退出房间了。userId\n \n路由: 2 - 4 --- 【玩家准备】 --- 【FightRoomAction:146】【ready】\n 方法参数: BoolValue ready true 表示准备，false 则是取消准备\n 方法返回值: void \n 广播推送: PlayerReady 有玩家准备或取消准备了\n \n路由: 2 - 5 --- 【房间列表】 --- 【FightRoomAction:222】【listRoom】\n 方法返回值: ByteValueList 房间列表\n \n路由: 2 - 6 --- 【玩家在游戏中的操作】 --- 【FightRoomAction:191】【operation】\n 方法参数: FightOperationCommand command 玩家操作数据\n 方法返回值: void \n \n路由: 2 - 7 --- 【开始游戏】 --- 【FightRoomAction:162】【startGame】\n 方法返回值: void \n \n\n==================== 其它广播推送 ====================\n路由: 2 - 51 --- 广播推送: FightRoomNotice (房间更新通知)\n路由: 2 - 50 --- 广播推送: FightPlayer (有新玩家加入房间)\n路由: 2 - 52 --- 广播推送: IntValue (对局开始，通知玩家开始选择。round 当前对局数)\n路由: 2 - 53 --- 广播推送: LongValue (通知其他玩家，有玩家做了选择。userId)\n路由: 2 - 56 --- 广播推送: none (解散房间)\n路由: 2 - 54 --- 广播推送: ByteValueList (广播玩家对局分数)\n路由: 2 - 55 --- 广播推送: none (游戏结束)\n==================== 错误码 ====================\n -1008 : 绑定的游戏逻辑服不存在 \n -1007 : 强制玩家下线 \n -1006 : 数据不存在 \n -1005 : class 不存在 \n -1004 : 请先登录 \n -1003 : 心跳超时相关 \n -1002 : 路由错误 \n -1001 : 参数验错误 \n -1000 : 系统其它错误 \n 1 : 玩家在房间里 \n 3 : 房间不存在 \n 4 : 非法操作 \n 6 : 开始游戏需要的最小人数不足 \n 7 : 请等待其他玩家准备 \n 8 : 房间空间不足，人数已满 \n\n```\n\n---\n\n\n\n**[light-game-room]**\n\n\n[#278](https://github.com/iohao/ioGame/issues/278) 桌游类、房间类游戏的扩展模块，简化与规范化房间管理相关的、开始游戏流程相关的、玩法操作相关的相关扩展\n\n\n\nlight-game-room 房间，是 ioGame 提供的一个轻量小部件 - 可按需选择的模块。\n\n> **light-game-room + 领域事件 + 内置 Kit = 轻松搞定桌游类游戏**\n\n\n\n该模块是桌游类、房间类游戏的解决方案。比较适合桌游类、房间类的游戏基础搭建，基于该模型可以做一些如，炉石传说、三国杀、斗地主、麻将 ...等类似的桌游。或者说只要是房间类的游戏，该模型都适用。比如，CS、泡泡堂、飞行棋、坦克大战 ...等。\n\n\n\n如果你计划做一些桌游类的游戏，那么推荐你基于该模块做扩展。该模块遵循面向对象的设计原则，没有强耦合，可扩展性强。且帮助开发者屏蔽了很多重复性的工作，并可为项目中的功能模块结构、开发流程等进行清晰的组织定义，减少了后续的项目维护成本。\n\n\n\n**主要解决的问题与职责**\n\n桌游、房间类的游戏在功能职责上可以分为 3 大类，分别是\n\n1. **房间管理相关的**\n 1. 管理着所有的房间、查询房间列表、房间的添加、房间的删除、房间与玩家之间的关联、房间查找（通过 roomId 查找、通过 userId 查找）。\n1. **开始游戏流程相关的**\n 1. 通常桌游、房间类的游戏都有一些固定的流程，如创建房间、玩家进入房间、玩家退出房间、解散房间、玩家准备、开始游戏 ...等。\n 2. 开始游戏时，需要做开始前的验证，如房间内的玩家是否符足够 ...等，当一切符合业务时，才是真正的开始游戏。\n1. **玩法操作相关的**\n 1. 游戏开始后，由于不同游戏之间的具体操作是不相同的。如坦克的射击，炉石的战前选牌、出牌，麻将的吃、碰、杠、过、胡，回合制游戏的普攻、防御、技能 ...等。\n 2. 由于玩法操作的不同，所以我们的玩法操作需要是可扩展的，并用于处理具体的玩法操作。同时这种扩展方式更符合单一职责，使得我们后续的扩展与维护成本更低。\n\n以上功能职责（房间管理相关、流程相关、玩法操作相关）属于相对通用的功能。如果每款游戏都重复的做这些工作，除了枯燥之外，还将浪费巨大的人力成本。\n\n而当前模块则能很好的帮助开发者屏蔽这些重复性的工作，并可为项目中的功能模块结构、开发流程等进行清晰的组织定义，减少了后续的项目维护成本。更重要的是有相关文档，将来当你的团队有新进成员时，可以快速的上手。\n\n---\n\n\n\n**room 实战简介**\n\n\n文档中，我们基于该 room 模块做一个实战示例，该示例整体比较简单，多名玩家在房间里猜拳（石头、剪刀、布）得分。实战示例包括了前后端，前端使用 [FXGL](https://github.com/almasB/FXGL) 引擎，这样开发者在学习时，只需 JDK 环境就可以了，而不需要安装更多的环境。启动游戏后玩家会将加入大厅（类似地图），多名玩家相互可见，并且玩家可以在大厅内移动。\n\n\n\n---\n\n\n\n[示例集合整理] \n\n\n\n\n| github | gitee |\n| ---------------------------------------------------------- | --------------------------------------------------------- |\n| [ioGame 示例集合](https://github.com/iohao/ioGameExamples) | [ioGame 示例集合](https://gitee.com/iohao/ioGameExamples) |\n\n---\n\n\n\n### 2024-05-11 - v21.7\n\nhttps://github.com/iohao/ioGame/releases/tag/21.7\n\n\n\n**版本更新汇总**\n\n1. [core] [#112](https://github.com/iohao/ioGame/issues/112) protobuf 协议类添加检测，通过 action 构建时的监听器实现\n2. [core] [#272](https://github.com/iohao/ioGame/issues/272) 业务框架 - 提供 action 构建时的监听回调\n3. [core] [#274](https://github.com/iohao/ioGame/issues/274) 优化、提速 - 预生成 jprotobuf 协议类的代理，通过 action 构建时的监听器实现\n4. [broker] fix [#277](https://github.com/iohao/ioGame/issues/277) 、[#280](https://github.com/iohao/ioGame/issues/280) 偶现 BrokerClientType 为空\n5. [external] [#271](https://github.com/iohao/ioGame/issues/271) 游戏对外服 - 内置与可选 handler - log 相关的打印（触发异常、断开连接时）\n6. [room] 简化命名: AbstractPlayer --> Player、AbstractRoom --> Room\n7. 其他优化：预先生成游戏对外服统一协议的代理类及内置的协议碎片相关代理类，优化 action 参数解析\n\n\n\n**[external]**\n\n[#271](https://github.com/iohao/ioGame/issues/271) 游戏对外服 - 内置与可选 handler - log 相关的打印（触发异常、断开连接时）\n\n\n\n\n**[core]**\n\n[#272](https://github.com/iohao/ioGame/issues/272) 业务框架 - 提供 action 构建时的监听回调\n\n开发者可以利用 ActionParserListener 接口来观察 action 构建过程，或者做一些额外的扩展。\n\n\n\n扩展示例参考\n\n```java\n// 简单打印\npublic final class YourActionParserListener implements ActionParserListener {\n @Override\n public void onActionCommand(ActionParserContext context) {\n ActionCommand actionCommand = context.getActionCommand();\n log.info(actionCommand);\n }\n}\n\nvoid test() {\n BarSkeletonBuilder builder = ...;\n builder.addActionParserListener(new YourActionParserListener());\n}\n```\n\n\n\n[#112](https://github.com/iohao/ioGame/issues/112) protobuf 协议类添加检测，通过 action 构建时的监听器实现\n\n如果当前使用的编解码器为 ProtoDataCodec 时，当 action 的参数或返回值的类没有添加 ProtobufClass 注解时（通常是忘记添加），给予一些警告提示。\n\n```java\n// 该协议类没有添加 ProtobufClass 注解\nclass Bird {\n public String name;\n}\n\n@ActionController(1)\npublic class MyAction {\n @ActionMethod(1)\n public Bird testObject() {\n return new Bird();\n }\n}\n======== 注意，协议类没有添加 ProtobufClass 注解 ========\nclass com.iohao.game.action.skeleton.core.action.Bird\n```\n\n\n\n[#274](https://github.com/iohao/ioGame/issues/274) 优化、提速 - 预生成 jprotobuf 协议类的代理，通过 action 构建时的监听器实现\n\n如果当前使用的编解码器为 ProtoDataCodec 时，会在启动时就预先生成好 jprotobuf 协议类对应的代理类（用于 .proto 相关的 编码、解码），而不必等到用时在创建该代理类。从而达到整体优化提速的效果。\n\n \n\n在此之前，在没做其他设置的情况下，首次访问 action 时，如果参数使用的 jprotobuf 协议类，那么在解码该参数时，会通过 `ProtobufProxy.create` 来创建对应的代理类（类似 .proto 相关的 编码、解码）。之后再访问时，才会从缓存中取到对应的代理类。\n\n \n\n该优化默认开启，开发者可以不需要使用与配置跟 jprotobuf-precompile-plugin 插件相关的了。\n\n\n\n已经预先生成的代理类有\n\n- 游戏对外服统一协议 ExternalMessage\n- 所有开发者定义的 action 的方法参数及返回值\n- 解决协议碎片相关，如 int、int list、String、String list、long、long list、ByteValueList ...等\n\n\n\n**[room]**\n简化命名: AbstractPlayer --> Player、AbstractRoom --> Room\n\n\n\n**其他优化**\n\n优化 action 参数解析\n\n---\n\n\n\n### 2024-04-23 - v21.6\n\nhttps://github.com/iohao/ioGame/releases/tag/21.6\n\n\n\n**版本更新汇总**\n\n1. [#264](https://github.com/iohao/ioGame/issues/264) 新增属性值变更监听特性\n2. 模拟客户端新增与服务器断开连接的方法。模拟客户端新增是否活跃的状态属性。\n3. [#265](https://github.com/iohao/ioGame/issues/265) 从游戏对外服中获取玩家相关数据 - 模拟玩家请求。\n4. 任务相关：TaskListener 接口增加异常回调方法，用于接收异常信息；当 triggerUpdate 或 onUpdate 方法抛出异常时，将会传递到该回调方法中。\n5. [#266](https://github.com/iohao/ioGame/issues/266) 新增 RangeBroadcast 范围内的广播功能，这个范围指的是，可指定某些用户进行广播。\n6. AbstractRoom 增加 ifPlayerExist、ifPlayerNotExist 方法。\n\n------\n\n**属性监听特性**\n\n[#264](https://github.com/iohao/ioGame/issues/264) 新增属性值变更监听特性\n\n\n属性可添加监听器，当某些属性值的发生变化时，触发监听器。\n\n\n\n**使用场景举例**\n\n比如玩家的血量低于一定值时，需要触发无敌状态；此时，我们就可以监听玩家的血量，并在该属性上添加一个对应的监听器来观察血量的变化，当达到预期值时就触发对应的业务。\n\n \n\n类似的使用场景还有很多，这里就不过多的举例了。属性监听的特点在于属性变化后会触发监听器。\n\n\n\n**属性监听特点**\n\n- 可为属性添加监听器，用于观察属性值的变化。\n- 属性可以添加多个监听器。\n- 属性的监听器可以移除。\n\n\n\n**框架已经内置了几个属性实现类，分别是：**\n\n- IntegerProperty\n- LongProperty\n- StringProperty\n- BooleanProperty\n- ObjectProperty\n\n------\n\nfor example - 添加监听器\n\nBooleanProperty\n\n当 BooleanProperty 对象的值发生改变时，触发监听器。\n\n```java\nvar property = new BooleanProperty();\n// 添加一个监听器。\nproperty.addListener((observable, oldValue, newValue) -> {\n log.info(\"oldValue:{}, newValue:{}\", oldValue, newValue);\n});\n\nproperty.get(); // value is false\nproperty.set(true); // 值变更时，将会触发监听器\nproperty.get(); // value is true\n```\n\n\n\nIntegerProperty\n\n当 IntegerProperty 对象的值发生改变时，触发监听器。\n\n```java\nvar property = new IntegerProperty();\n// add listener monitor property object\nproperty.addListener((observable, oldValue, newValue) -> {\n log.info(\"oldValue:{}, newValue:{}\", oldValue, newValue);\n});\n\nproperty.get(); // value is 0\nproperty.set(22); // When the value changes,listeners are triggered\nproperty.get(); // value is 22\n\nproperty.increment(); // value is 23. will trigger listeners\n```\n\n------\n\nfor example - 移除监听器\n\n下面这个示例，我们将 property 初始值设置为 10，随后添加了一个监听器；当监听器观察到新值为 9 时，就从 observable 中移除自己（这个自己指的是监听器本身），而 observable 则是 IntegerProperty。\n\n```java\n@Test\npublic void remove1() {\n IntegerProperty property = new IntegerProperty(10);\n // 添加一个监听器\n property.addListener(new PropertyChangeListener<>() {\n @Override\n public void changed(PropertyValueObservable observable, Number oldValue, Number newValue) {\n log.info(\"1 - newValue : {}\", newValue);\n\n if (newValue.intValue() == 9) {\n // 移除当前监听器\n observable.removeListener(this);\n }\n }\n });\n\n property.decrement(); // value 是 9，并触发监听器\n property.decrement(); // value 是 8，由于监听器已经移除，所以不会触发任何事件。\n}\n```\n\n\n\n下面的示例中，我们定义了一个监听器类 OnePropertyChangeListener 并实现了 PropertyChangeListener 监听器接口。示例中，我们通过 OnePropertyChangeListener 对象的引用来移除监听器。\n\n```java\n@Test\npublic void remove2() {\n // 监听器\n OnePropertyChangeListener onePropertyChangeListener = new OnePropertyChangeListener();\n \n // 属性\n IntegerProperty property = new IntegerProperty();\n // 添加监听器\n property.addListener(onePropertyChangeListener);\n\n property.increment(); // value == 1，并触发监听器\n property.removeListener(onePropertyChangeListener); // 移除监听器\n property.increment(); // value == 2，由于监听器已经移除，所以不会触发任何事件。\n}\n\n// 自定义的监听器\nclass OnePropertyChangeListener implements PropertyChangeListener {\n @Override\n public void changed(PropertyValueObservable observable, Number oldValue, Number newValue) {\n log.info(\"oldValue:{}, newValue:{}, observable:{}\", oldValue, newValue, observable);\n }\n}\n```\n\n------\n\n**属性监听 - 小结**\n\n属性监听在使用上是简单的，如果你的业务中**有关于属性变化后需要触发某些事件的**，可以考虑引用该特性。框架为 int、long、boolean、Object、String 等基础类型提供了对应的属性监听。\n\n\n\n属性监听特性支持添加多个监听器，支持移除监听器。\n\n------\n\n\n\n**模拟客户端相关**\n\n- 模拟客户端新增与服务器断开连接的方法。\n- 模拟客户端新增是否活跃的状态属性。\n\n```java\nClientUser clientUser = ...;\n// 是否活跃，true 表示玩家活跃\nclientUser.isActive();\n// 关闭模拟客户端连接\nclientUser.getClientUserChannel().closeChannel();\n```\n\n------\n\n\n\n**访问游戏对外服与扩展相关**\n\n\nRequestCollectExternalMessage 增加 userId 字段。\n\n\n\n[#265](https://github.com/iohao/ioGame/issues/265) 模拟玩家请求时 - 从游戏对外服中获取在线玩家相关数据\n\n新增 UserHeadMetadataExternalBizRegion，从用户（玩家）所在游戏对外服中获取用户自身的数据，如用户所绑定的游戏逻辑服、元信息 ...等\n\n```java\n@Slf4j\n@RestController\n@RequestMapping(\"other\")\npublic class OtherController {\n static final AtomicLong msgId = GameManagerController.msgId;\n /** 为了方便测试，这里指定一个 userId 来模拟玩家 */\n static final long userId = GameManagerController.userId;\n\n @GetMapping(\"/notice\")\n public String notice() {\n log.info(\"other notice\");\n // 使用协议碎片特性 https://iohao.github.io/game/docs/manual/protocol_fragment\n StringValue data = StringValue.of(\"other GM web msg \" + msgId.incrementAndGet());\n // 模拟请求 : 路由 - 业务数据\n RequestMessage requestMessage = BarMessageKit.createRequestMessage(ExchangeCmd.of(ExchangeCmd.notice), data);\n\n // 设置需要模拟的玩家\n HeadMetadata headMetadata = requestMessage.getHeadMetadata();\n headMetadata.setUserId(userId);\n\n // 从游戏对外服中获取一些用户（玩家的）自身的数据，如元信息、所绑定的游戏逻辑服 ...等\n Optional headMetadataOptional = ExternalCommunicationKit.employHeadMetadata(requestMessage);\n\n if (headMetadataOptional.isPresent()) {\n // 发起模拟请求\n extractedRequestLogic(requestMessage);\n\n // 打印从游戏对外服获取的元信息\n byte[] attachmentData = headMetadata.getAttachmentData();\n ExchangeAttachment attachment = DataCodecKit.decode(attachmentData, ExchangeAttachment.class);\n return \"other notice 玩家的元信息: %s - %s\".formatted(attachment, msgId.get());\n } else {\n return \"other notice 玩家 %s 不在线，无法获取玩家的元信息 - %s\".formatted(userId, msgId.get());\n }\n }\n\n private void extractedRequestLogic(RequestMessage requestMessage) {\n // 向逻辑服发送请求，该模拟请求具备了玩家的元信息。\n BrokerClient brokerClient = MyKit.brokerClient;\n InvokeModuleContext invokeModuleContext = brokerClient.getInvokeModuleContext();\n invokeModuleContext.invokeModuleVoidMessage(requestMessage);\n }\n}\n```\n\n------\n\n\n\n**任务工具相关**\n\nTaskListener 接口增加异常回调方法 `void onException(Throwable e)`，用于接收异常信息；当 triggerUpdate 或 onUpdate 方法抛出异常时，将会传递到该回调方法中。\n\n```java\n@Test\npublic void testException() throws InterruptedException {\n AtomicBoolean hasEx = new AtomicBoolean(false);\n TaskKit.runOnce(new OnceTaskListener() {\n @Override\n public void onUpdate() {\n // 模拟一个业务异常\n throw new RuntimeException(\"hello exception\");\n }\n\n @Override\n public void onException(Throwable e) {\n hasEx.set(true);\n // 触发异常后，将来到这里\n log.error(e.getMessage(), e);\n }\n }, 10, TimeUnit.MILLISECONDS);\n\n TimeUnit.MILLISECONDS.sleep(200);\n Assert.assertTrue(hasEx.get()); // true\n}\n```\n\n------\n\n\n\n**业务框架相关 - [common-core]**\n\n[#266](https://github.com/iohao/ioGame/issues/266) 新增 RangeBroadcast 范围内的广播功能，这个范围指的是，可指定某些用户进行广播。\n\n\n\n在执行广播前，开发者可以自定义业务逻辑，如\n\n- 添加一些需要广播的用户\n- 删除一些不需要接收广播的用户\n- 可通过重写 logic、trick 方法来做一些额外扩展\n\n```java\n// example - 1\nnew RangeBroadcast(flowContext)\n // 需要广播的数据\n .setResponseMessage(responseMessage)\n // 添加需要接收广播的用户\n .addUserId(1)\n .addUserId(2)\n .addUserId(List.of(3L, 4L, 5L))\n // 排除一些用户，被排除的用户将不会接收到广播\n .removeUserId(1)\n // 执行广播\n .execute();\n\n// example - 2\nnew RangeBroadcast(flowContext)\n // 需要广播的数据\n .setResponseMessage(cmdInfo, playerReady)\n // 添加需要接收广播的用户\n .addUserId(1)\n // 执行广播\n .execute();\n```\n\n------\n\n**[light-game-room] 房间模块**\n\n- 移除 AbstractRoom broadcast 系列方法，开发者可使用 RoomBroadcastFlowContext 接口实现旧的兼容。\n- 移除 AbstractRoom createSend 方法，开发者可使用 ofRangeBroadcast 系列来代替。AbstractRoom 新增 RoomBroadcastEnhance，实现房间内的广播增强，该系列在语义上更清晰。\n\n\n\n```java\nfinal RoomService roomService = ...;\n\n@ActionMethod(RoomCmd.ready)\npublic void ready(boolean ready, FlowContext flowContext) {\n long userId = flowContext.getUserId();\n // 得到玩家所在的房间\n AbstractRoom room = this.roomService.getRoomByUserId(userId);\n \n // 准备\n PlayerReady playerReady = new PlayerReady();\n playerReady.userId = userId;\n playerReady.ready = ready;\n \n // 通知房间内的所有玩家，有玩家准备或取消准备了\n room.ofRangeBroadcast(flowContext)\n // 响应数据（路由、业务数据）\n .setResponseMessage(flowContext.getCmdInfo(), playerReady)\n .execute();\n}\n\n// 准备或取消准备\n@ProtobufClass\n@FieldDefaults(level = AccessLevel.PUBLIC)\npublic class PlayerReady {\n /** 当前操作的玩家 userId */\n long userId;\n /** true 表示准备 */\n boolean ready;\n}\n```\n\n------\n\n\n\n**AbstractRoom 增加 ifPlayerExist、ifPlayerNotExist 方法。**\n\n**ifPlayerExist 方法**\n\n如果玩家在房间内，就执行给定的操作，否则不执行任何操作。\n\n```java\nRoomService roomService = ...;\nAbstractRoom room = ...;\n// 如果玩家不在房间内，就创建一个玩家，并让玩家加入房间\nroom.ifPlayerNotExist(userId, () -> {\n // 玩家加入房间\n FightPlayerEntity newPlayer = new FightPlayerEntity();\n newPlayer.setId(userId);\n \n this.roomService.addPlayer(room, newPlayer);\n});\n```\n\n\n\n**ifPlayerNotExist 方法**\n\n如果玩家不在房间内，就执行给定的操作，否则不执行任何操作。\n\n```java\nAbstractRoom room = ...;\n// 有新玩家加入房间，通知其他玩家\nroom.ifPlayerExist(userId, (FightPlayerEntity playerEntity) -> {\n FightPlayer fightPlayer = FightMapstruct.ME.convert(playerEntity);\n room.ofRangeBroadcast(flowContext)\n .setResponseMessage(RoomCmd.of(RoomCmd.playerEnterRoomBroadcast), fightPlayer)\n // 排除不需要通知的玩家（当前 userId 是自己）\n .removeUserId(userId)\n .execute();\n});\n```\n\n---\n\n\n\n### 2024-04-16 - v21.5\n\nhttps://github.com/iohao/ioGame/releases/tag/21.5\n\n\n\n1. 增强 ClassScanner 类 \n2. 优化模拟客户端 \n3. [#258](about:blank) 文档生成，兼容 gradle 编译路径 \n4. enhance jprotobuf，临时解决打包后不能在 linux java21 环境运行的问题，see [java21，springBoot3.2 打 jar 后使用异常 · Issue #211 · jhunters/jprotobuf (github.com)](https://github.com/jhunters/jprotobuf/issues/211) \n5. 生成 .proto 时，在最后打印文件路径 \n\n1. [#255](https://github.com/iohao/ioGame/issues/255) 关于 Proto 生成排除属性问题\n\n```java\n/**\n * 动物\n */\n@ProtobufClass\n@FieldDefaults(level = AccessLevel.PUBLIC)\npublic class Animal {\n /** id */\n int id;\n /** 动物类型 - 枚举测试 */\n AnimalType animalType;\n \t/** 年龄 - 忽略的属性*/\n @Ignore\n String age;\n}\n```\n\n\n\n生成后的 .proto\n\n```protobuf\n// 动物\nmessage Animal {\n // id\n int32 id = 1;\n // 动物类型 - 枚举测试\n AnimalType animalType = 2;\n}\n```\n\n---\n\n\n\n### 2024-03-28 - v21.4\n\nhttps://github.com/iohao/ioGame/releases/tag/21.4\n\n\n\n\n[ #253](https://github.com/iohao/ioGame/issues/253)\n\n> CreateRoomInfo.createUserId int --> long\n\n\n\nExecutorRegion\n\n> 1. 优化默认创建策略\n> 2. 优化 ExecutorRegionKit，SimpleThreadExecutorRegion 默认使用全局单例，减少对象的创建。\n\n\n\nproto 文档生成时，默认指定为 StandardCharsets.UTF_8\n\n> javaProjectBuilder.setEncoding(StandardCharsets.UTF_8.name());\n\n\n\n玩家下线时，使用自身所关联的线程处理。\n\n> SocketUserSessions removeUserSession\n\n```java\npublic void removeUserSession(SocketUserSession userSession) {\n\n if (Objects.isNull(userSession)) {\n return;\n }\n\n long userId = userSession.getUserId();\n ExecutorRegionKit.getSimpleThreadExecutor(userId)\n .executeTry(() -> internalRemoveUserSession(userSession));\n}\n```\n\n---\n\n\n\n### 2024-03-11 - v21.3\n\nhttps://github.com/game-town/ioGame/releases/tag/21.3\n\n\n\n[#250](https://github.com/game-town/ioGame/issues/250) 游戏对外服 - 自定义编解码 - WebSocketMicroBootstrapFlow\n\n\n\n\n重写 WebSocketMicroBootstrapFlow createExternalCodec 方法，用于创建开发者自定义的编解码，其他配置则使用 pipelineCodec 中的默认配置。\n\n```java\nDefaultExternalServerBuilder builder = ...;\n\nbuilder.setting().setMicroBootstrapFlow(new WebSocketMicroBootstrapFlow() {\n @Override\n protected MessageToMessageCodec createExternalCodec() {\n // 开发者自定义的编解码实现类。\n return new YourWsExternalCodec();\n }\n});\n```\n\n\n\n以下展示的是 WebSocketMicroBootstrapFlow pipelineCodec 相关代码\n\n```java\npublic class WebSocketMicroBootstrapFlow extends SocketMicroBootstrapFlow {\n ... 省略部分代码\n @Override\n public void pipelineCodec(PipelineContext context) {\n // 添加 http 相关 handler\n this.httpHandler(context);\n\n // 建立连接前的验证 handler\n this.verifyHandler(context);\n\n // 添加 websocket 相关 handler\n this.websocketHandler(context);\n\n // websocket 编解码\n var externalCodec = this.createExternalCodec();\n context.addLast(\"codec\", externalCodec);\n }\n\n @Override\n protected MessageToMessageCodec createExternalCodec() {\n // createExternalCodec 相当于一个钩子方法。\n return new WebSocketExternalCodec();\n }\n};\n```\n\n\n\n[#249](https://github.com/game-town/ioGame/issues/249)\n将集群启动顺序放到 Broker（游戏网关）之后。\n\n集群增减和逻辑服 Connect 增减使用同一线程处理。\n\nIoGameGlobalConfig brokerClusterLog 集群相关日志不开启。\n\n---\n\n\n\n### 2024-02-22 - v21.2\n\n修复版本号显示错误问题（该版本没有功能上的更新与修改，不升级也不影响）\n\n\n\n### 2024-02-21 - v21.1\n\nhttps://github.com/game-town/ioGame/releases/tag/21.1\n\n\n\nioGame21 首发计划\n\n| 功能支持 | 完成 | 描述 | issu |\n|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----|-----------|--------------------------------------------------------|\n| 游戏对外服开放自定义协议 | ✅ | 功能增强 | [#213](https://github.com/game-town/ioGame/issues/213) |\n| 游戏对外服缓存 | ✅ | 功能增强、性能提升 | [#76](https://github.com/game-town/ioGame/issues/76) |\n| FlowContext 增加通信能力，提供同步、异步、异步回调的便捷使用 | ✅ | 功能增强 | [#235](https://github.com/game-town/ioGame/issues/235) |\n| 虚拟线程支持; 各逻辑服之间通信阻塞部分，改为使用虚拟线程，避免阻塞业务线程 | ✅ | 功能增强、性能提升 | |\n| 默认不使用 bolt 线程池，减少上下文切换。 ioGame17：netty --> bolt 线程池 --> ioGame 线程池。 ioGame21： 1. netty --> ioGame 线程池。 2. 部分业务将直接在 netty 线程中消费业务。 | ✅ | 性能提升 | |\n| 全链路调用日志跟踪；日志增强 traceId | ✅ | 功能增强 | [#230](https://github.com/game-town/ioGame/issues/230) |\n| 移除过期代码 | ✅ | 整理 | [#237](https://github.com/game-town/ioGame/issues/239) |\n| 分布式事件总线可以代替 redis pub sub 、 MQ ，并且具备全链路调用日志跟踪，这点是中间件产品做不到的。 | ✅ | 功能增强 | [#228](https://github.com/game-town/ioGame/issues/228) |\n| 日志库使用新版本 slf4j 2.0 | ✅ | | |\n| 心跳响应前的回调 | ✅ | 功能增强 | [#234](https://github.com/game-town/ioGame/issues/234) |\n| FlowContext 增加更新、获取元信息的便捷使用 | ✅ | 功能增强 | [#236](https://github.com/game-town/ioGame/issues/236) |\n\n\n\n### 2024\n\n#### ioGame21 首发内容简介\n\n在 ioGame21 中，该版本做了数百项优化及史诗级增强。\n\n- 文档方面\n- 线程管理域方面的开放与统一、减少线程池上下文切换\n- FlowContext 得到了**史诗级**的增强。\n- 新增通讯方式 - 分布式事件总线\n- 游戏对外服方面增强\n- 全链路调用日志跟踪\n- 各逻辑服之间通信阻塞部分，改为使用虚拟线程, 避免阻塞业务线程，从而使得框架的吞吐量得到了巨大的提升。\n\n\n\n##### 游戏对外服相关\n\n[#76](https://github.com/game-town/ioGame/issues/76) 游戏对外服缓存 \n\n\n\n\n游戏对外服缓存，可以将一些热点的业务数据缓存在游戏对外服中，玩家每次访问相关路由时，会直接从游戏对外服的内存中取数据。这样可以避免反复请求游戏逻辑服，从而达到性能的超级提升；\n\n```java\nprivate static void extractedExternalCache() {\n // 框架内置的缓存实现类\n DefaultExternalCmdCache externalCmdCache = new DefaultExternalCmdCache();\n // 添加到配置中\n ExternalGlobalConfig.externalCmdCache = externalCmdCache;\n // 配置缓存 3-1\n externalCmdCache.addCmd(3, 1);\n}\n```\n\n\n\n[#213](https://github.com/game-town/ioGame/issues/213) 游戏对外服开放自定义协议 \n\n\n开发者可自定义游戏对外服协议，用于代替框架默认的 ExternalMessage 公共对外协议。\n\n\n\n[#234](https://github.com/game-town/ioGame/issues/234) 心跳响应前的回调 \n\n\n在部分场景下，在响应心跳前可添加当前时间，使得客户端与服务器时间同步。\n\n```java\n@Slf4j\npublic class DemoIdleHook implements SocketIdleHook {\n ... ... 省略部分代码\n volatile byte[] timeBytes;\n\n public DemoIdleHook() {\n updateTime();\n // 每秒更新当前时间\n TaskKit.runInterval(this::updateTime, 1, TimeUnit.SECONDS);\n }\n\n private void updateTime() {\n LongValue data = LongValue.of(TimeKit.currentTimeMillis());\n // 避免重复序列化，这里提前序列化好时间数据\n timeBytes = DataCodecKit.encode(data);\n }\n\n @Override\n public void pongBefore(BarMessage idleMessage) {\n // 把当前时间戳给到心跳接收端\n idleMessage.setData(timeBytes);\n }\n}\n```\n\n\n\n##### FlowContext - 跨服通信\n\n[#235](https://github.com/game-town/ioGame/issues/235) FlowContext 增加通信能力，提供同步、异步、异步回调的便捷使用 \n\n\n```java\n// 跨服请求 - 同步、异步回调演示\nvoid invokeModuleMessage() {\n // 路由、请求参数\n ResponseMessage responseMessage = flowContext.invokeModuleMessage(cmdInfo, yourData);\n RoomNumMsg roomNumMsg = responseMessage.getData(RoomNumMsg.class);\n log.info(\"同步调用 : {}\", roomNumMsg.roomCount);\n\n // --- 此回调写法，具备全链路调用日志跟踪 ---\n // 路由、请求参数、回调\n flowContext.invokeModuleMessageAsync(cmdInfo, yourData, responseMessage -> {\n RoomNumMsg roomNumMsg = responseMessage.getData(RoomNumMsg.class);\n log.info(\"异步回调 : {}\", roomNumMsg.roomCount);\n });\n}\n\n// 广播\npublic void broadcast(FlowContext flowContext) {\n // 全服广播 - 路由、业务数据\n flowContext.broadcast(cmdInfo, yourData);\n\n // 广播消息给单个用户 - 路由、业务数据、userId\n long userId = 100;\n flowContext.broadcast(cmdInfo, yourData, userId);\n\n // 广播消息给指定用户列表 - 路由、业务数据、userIdList\n List userIdList = new ArrayList<>();\n userIdList.add(100L);\n userIdList.add(200L);\n flowContext.broadcast(cmdInfo, yourData, userIdList);\n\n // 给自己发送消息 - 路由、业务数据\n flowContext.broadcastMe(cmdInfo, yourData);\n\n // 给自己发送消息 - 业务数据\n // 路由则使用当前 action 的路由。\n flowContext.broadcastMe(yourData);\n}\n```\n\n\n\n[#236](https://github.com/game-town/ioGame/issues/236) FlowContext 增加更新、获取元信息的便捷使用 \n\n\n```java\nvoid test(MyFlowContext flowContext) {\n // 获取元信息\n MyAttachment attachment = flowContext.getAttachment();\n attachment.nickname = \"渔民小镇\";\n\n // [同步]更新 - 将元信息同步到玩家所在的游戏对外服中\n flowContext.updateAttachment();\n\n // [异步无阻塞]更新 - 将元信息同步到玩家所在的游戏对外服中\n\tflowContext.updateAttachmentAsync();\n}\n\npublic class MyFlowContext extends FlowContext {\n MyAttachment attachment;\n\n @Override\n @SuppressWarnings(\"unchecked\")\n public MyAttachment getAttachment() {\n if (Objects.isNull(attachment)) {\n this.attachment = this.getAttachment(MyAttachment.class);\n }\n\n return this.attachment;\n }\n}\n```\n\n\n\n##### 线程相关 - 无锁高并发\n\n\n\n\n虚拟线程支持，各逻辑服之间通信阻塞部分使用虚拟线程来处理，避免阻塞业务线程。\n\n\n\n默认不使用 bolt 线程池，减少上下文切换。ioGame21 业务消费的线程相关内容如下：\n\n1. netty --> ioGame 线程池。\n2. 部分业务将直接在 netty 线程中消费业务。\n\n\n\n在 ioGame21 中，框架内置了 3 个线程执行器管理域，分别是\n\n1. UserThreadExecutorRegion ，用户线程执行器管理域。\n2. UserVirtualThreadExecutorRegion ，用户虚拟线程执行器管理域。\n3. SimpleThreadExecutorRegion ，简单的线程执行器管理域。\n\n\n\n**从工具类中得到与用户（玩家）所关联的线程执行器**\n\n```java\n@Test\npublic void userThreadExecutor() {\n long userId = 1;\n\n ThreadExecutor userThreadExecutor = ExecutorRegionKit.getUserThreadExecutor(userId);\n\n userThreadExecutor.execute(() -> {\n // print 1\n log.info(\"userThreadExecutor : 1\");\n });\n\n userThreadExecutor.execute(() -> {\n // print 2\n log.info(\"userThreadExecutor : 2\");\n });\n}\n\n@Test\npublic void getUserVirtualThreadExecutor() {\n long userId = 1;\n\n ThreadExecutor userVirtualThreadExecutor = ExecutorRegionKit.getUserVirtualThreadExecutor(userId);\n\n userVirtualThreadExecutor.execute(() -> {\n // print 1\n log.info(\"userVirtualThreadExecutor : 1\");\n });\n\n userVirtualThreadExecutor.execute(() -> {\n // print 2\n log.info(\"userVirtualThreadExecutor : 2\");\n });\n}\n\n@Test\npublic void getSimpleThreadExecutor() {\n long userId = 1;\n\n ThreadExecutor simpleThreadExecutor = ExecutorRegionKit.getSimpleThreadExecutor(userId);\n\n simpleThreadExecutor.execute(() -> {\n // print 1\n log.info(\"simpleThreadExecutor : 1\");\n });\n\n simpleThreadExecutor.execute(() -> {\n // print 2\n log.info(\"simpleThreadExecutor : 2\");\n });\n}\n```\n\n\n\n**从 FlowContext 中得到与用户（玩家）所关联的线程执行器**\n\n```java\nvoid executor() {\n // 该方法具备全链路调用日志跟踪\n flowContext.execute(() -> {\n log.info(\"用户线程执行器\");\n });\n\n // 正常提交任务到用户线程执行器中\n // getExecutor() 用户线程执行器\n flowContext.getExecutor().execute(() -> {\n log.info(\"用户线程执行器\");\n });\n}\n\nvoid executeVirtual() {\n // 该方法具备全链路调用日志跟踪\n flowContext.executeVirtual(() -> {\n log.info(\"用户虚拟线程执行器\");\n });\n\n // 正常提交任务到用户虚拟线程执行器中\n // getVirtualExecutor() 用户虚拟线程执行器\n flowContext.getVirtualExecutor().execute(() -> {\n log.info(\"用户虚拟线程执行器\");\n });\n\n // 示例演示 - 更新元信息（可以使用虚拟线程执行完成一些耗时的操作）\n flowContext.executeVirtual(() -> {\n log.info(\"用户虚拟线程执行器\");\n \n // 更新元信息\n flowContext.updateAttachment();\n \n // ... ... 其他业务逻辑\n });\n}\n```\n\n\n\n##### 日志相关\n\n日志库使用新版本 slf4j 2.x\n\n\n\n[#230](https://github.com/game-town/ioGame/issues/230) 支持全链路调用日志跟踪；\n\n\n\n\n**开启 traceId 特性**\n\n该配置需要在游戏对外服中设置，因为游戏对外服是玩家请求的入口。\n\n```java\n// true 表示开启 traceId 特性\nIoGameGlobalConfig.openTraceId = true;\n```\n\n\n\n将全链路调用日志跟踪插件 TraceIdInOut 添加到业务框架中，表示该游戏逻辑服需要支持全链路调用日志跟踪。如果游戏逻辑服没有添加该插件的，表示不需要记录日志跟踪。\n\n```java\nBarSkeletonBuilder builder = ...;\n// traceId\nTraceIdInOut traceIdInOut = new TraceIdInOut();\nbuilder.addInOut(traceIdInOut);\n```\n\n\n\n##### 分布式事件总线 - 跨服解耦\n\n[#228](https://github.com/game-town/ioGame/issues/228) 分布式事件总线是新增的通讯方式，可以代替 redis pub sub 、 MQ ...等中间件产品；分布式事件总线具备全链路调用日志跟踪，这点是中间件产品所做不到的。\n\n\n\n**ioGame 分布式事件总线，特点**\n\n- 使用方式与 Guava EventBus 类似\n- 具备**全链路调用日志跟踪**。（这点是中间件产品做不到的）\n- 支持跨多个机器、多个进程通信\n- 支持与多种不同类型的多个逻辑服通信\n- 纯 javaSE，不依赖其他服务，耦合性低。（不需要安装任何中间件）\n- 事件源和事件监听器之间通过事件进行通信，从而实现了模块之间的解耦\n- 当没有任何远程订阅者时，**将不会触发网络请求**。（这点是中间件产品做不到的）\n\n\n\n下面两个订阅者是分别在**不同的进程中**的，当事件发布后，这两个订阅者都能接收到 UserLoginEventMessage 消息。\n\n```java\n@ActionController(UserCmd.cmd)\npublic class UserAction {\n\t... 省略部分代码\n @ActionMethod(UserCmd.fireEvent)\n public String fireEventUser(FlowContext flowContext) {\n long userId = flowContext.getUserId();\n\n log.info(\"fire : {} \", userId);\n \n // 事件源\n var userLoginEventMessage = new UserLoginEventMessage(userId);\n // 发布事件\n flowContext.fire(userLoginEventMessage);\n\n return \"fireEventUser\";\n }\n}\n\n// 该订阅者在 【UserLogicStartup 逻辑服】进程中，与 UserAction 同在一个进程\n@EventBusSubscriber\npublic class UserEventBusSubscriber {\n @EventSubscribe(ExecutorSelector.userExecutor)\n public void userLogin(UserLoginEventMessage message) {\n log.info(\"event - 玩家[{}]登录，记录登录时间\", message.getUserId());\n }\n}\n\n// 该订阅者在 【EmailLogicStartup 逻辑服】进程中。\n@EventBusSubscriber\npublic class EmailEventBusSubscriber {\n @EventSubscribe\n public void mail(UserLoginEventMessage message) {\n long userId = message.getUserId();\n log.info(\"event - 玩家[{}]登录，发放 email 奖励\", userId);\n }\n}\n```\n\n\n\n##### 小结\n\n在 ioGame21 中，该版本做了数百项优化及史诗级增强。\n\n- 在线文档方面\n- 线程管理域方面的开放与统一、减少线程池上下文切换\n- FlowContext 增强\n- 新增通讯方式 - 分布式事件总线\n- 游戏对外服方面增强\n- 全链路调用日志跟踪\n\n\n\n#### ioGame17 迁移到 ioGame21\n\n文档：[17 迁移到 ioGame21](https://www.yuque.com/iohao/game/hcgsfobyoph9r74r) \n\n\n\n#### ioGame17 - 更新日志\n\nsee online [ioGame17 - 更新日志](https://iohao.github.io/game/docs/archive/version_log_17) "
},
{
"path": "common/README.md",
"content": "```text\n.\n├── common-core 业务框架\n└── common-kit 工具相关\n\n```"
},
{
"path": "common/common-core/README.md",
"content": "## 业务框架\n\n如果说 [sofa-bolt](https://www.sofastack.tech/projects/sofa-bolt/overview/) 是为了让 Java 程序员能将更多的精力放在基于网络通信的业务逻辑实现上。而业务框架正是解决业务逻辑如何方便实现这一问题上。业务框架是游戏框架的一部分，职责是简化程序员的业务逻辑实现，业务框架使程序员能够快速的开始编写游戏业务。\n\n\n\n业务框架对于每个 action （即业务的处理类） 都是通过 [asm](https://www.oschina.net/p/reflectasm) 与 Singleton、Flyweight 、Command 等设计模式结合，对 action 的获取上通过 array 来得到，是一种近原生的方式。\n\n\n\n业务框架平均每秒可以执行 1152 万次业务逻辑。\n\n"
},
{
"path": "common/common-core/pom.xml",
"content": "\n\n \n ioGame\n com.iohao.game\n 21.34\n ../../pom.xml\n \n 4.0.0\n\n common-core\n common-core for ioGame\n\n \n \n com.iohao.game\n common-kit\n ${project.parent.version}\n \n\n \n com.iohao.game\n common-validation\n ${project.parent.version}\n \n\n \n \n com.alibaba.fastjson2\n fastjson2\n ${fastjson.version}\n provided\n \n\n \n \n org.fusesource.jansi\n jansi\n ${jansi.version}\n \n\n \n \n com.thoughtworks.qdox\n qdox\n ${qdox.version}\n \n\n \n jakarta.validation\n jakarta.validation-api\n ${jakarta.validation-api.version}\n provided\n \n\n \n \n org.springframework\n spring-context\n ${spring.version}\n provided\n \n\n \n com.iohao.game\n light-jprotobuf\n ${project.parent.version}\n test\n \n\n \n \n org.hibernate.validator\n hibernate-validator\n ${hibernate-validator.version}\n test\n \n\n \n \n \n org.glassfish\n jakarta.el\n ${jakarta.el.version}\n test\n \n \n\n\n"
},
{
"path": "common/common-core/src/main/java/com/iohao/game/action/skeleton/IoGameVersion.java",
"content": "/*\n * ioGame\n * Copyright (C) 2021 - present 渔民小镇 （262610965@qq.com、luoyizhu@gmail.com） . All Rights Reserved.\n * # iohao.com . 渔民小镇\n *\n * This program is free software: you can redistribute it and/or modify\n * it under the terms of the GNU Affero General Public License as\n * published by the Free Software Foundation, either version 3 of the\n * License, or (at your option) any later version.\n *\n * This program is distributed in the hope that it will be useful,\n * but WITHOUT ANY WARRANTY; without even the implied warranty of\n * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n * GNU Affero General Public License for more details.\n *\n * You should have received a copy of the GNU Affero General Public License\n * along with this program. If not, see .\n */\npackage com.iohao.game.action.skeleton;\n\n/**\n * @author 渔民小镇\n * @date 2022-12-23\n */\npublic final class IoGameVersion {\n public static final String VERSION;\n\n static {\n String internalVersion = \"21.34\";\n\n VERSION = internalVersion\n .replace(\"\", \"\")\n .replace(\"\", \"\")\n ;\n }\n}\n"
},
{
"path": "common/common-core/src/main/java/com/iohao/game/action/skeleton/annotation/ActionController.java",
"content": "/*\n * ioGame\n * Copyright (C) 2021 - present 渔民小镇 （262610965@qq.com、luoyizhu@gmail.com） . All Rights Reserved.\n * # iohao.com . 渔民小镇\n *\n * This program is free software: you can redistribute it and/or modify\n * it under the terms of the GNU Affero General Public License as\n * published by the Free Software Foundation, either version 3 of the\n * License, or (at your option) any later version.\n *\n * This program is distributed in the hope that it will be useful,\n * but WITHOUT ANY WARRANTY; without even the implied warranty of\n * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n * GNU Affero General Public License for more details.\n *\n * You should have received a copy of the GNU Affero General Public License\n * along with this program. If not, see .\n */\npackage com.iohao.game.action.skeleton.annotation;\n\nimport java.lang.annotation.*;\n\n/**\n * 控制器注解, 一般用作类的路由\n *
\n * 类 cmd 注解\n * 一般用作类的路由\n *
\n *\n * @author 渔民小镇\n * @date 2021-12-12\n */\n@Target({ElementType.TYPE})\n@Retention(RetentionPolicy.RUNTIME)\n@Documented\npublic @interface ActionController {\n /**\n * @return 路由\n */\n int value();\n}"
},
{
"path": "common/common-core/src/main/java/com/iohao/game/action/skeleton/annotation/ActionMethod.java",
"content": "/*\n * ioGame\n * Copyright (C) 2021 - present 渔民小镇 （262610965@qq.com、luoyizhu@gmail.com） . All Rights Reserved.\n * # iohao.com . 渔民小镇\n *\n * This program is free software: you can redistribute it and/or modify\n * it under the terms of the GNU Affero General Public License as\n * published by the Free Software Foundation, either version 3 of the\n * License, or (at your option) any later version.\n *\n * This program is distributed in the hope that it will be useful,\n * but WITHOUT ANY WARRANTY; without even the implied warranty of\n * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n * GNU Affero General Public License for more details.\n *\n * You should have received a copy of the GNU Affero General Public License\n * along with this program. If not, see .\n */\npackage com.iohao.game.action.skeleton.annotation;\n\nimport java.lang.annotation.*;\n\n/**\n * 方法注解, 一般用作类方法的路由\n *
\n * 方法 subCmd 注解\n * 一般用作类方法的路由\n *
\n *\n * @author 渔民小镇\n * @date 2021-12-12\n */\n@Target({ElementType.METHOD})\n@Retention(RetentionPolicy.RUNTIME)\n@Documented\npublic @interface ActionMethod {\n /**\n * subCmd int\n *\n * @return subCmd\n */\n int value();\n}\n"
},
{
"path": "common/common-core/src/main/java/com/iohao/game/action/skeleton/annotation/DocActionSend.java",
"content": "/*\n * ioGame\n * Copyright (C) 2021 - present 渔民小镇 （262610965@qq.com、luoyizhu@gmail.com） . All Rights Reserved.\n * # iohao.com . 渔民小镇\n *\n * This program is free software: you can redistribute it and/or modify\n * it under the terms of the GNU Affero General Public License as\n * published by the Free Software Foundation, either version 3 of the\n * License, or (at your option) any later version.\n *\n * This program is distributed in the hope that it will be useful,\n * but WITHOUT ANY WARRANTY; without even the implied warranty of\n * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n * GNU Affero General Public License for more details.\n *\n * You should have received a copy of the GNU Affero General Public License\n * along with this program. If not, see .\n */\npackage com.iohao.game.action.skeleton.annotation;\n\nimport com.iohao.game.action.skeleton.core.doc.BroadcastDocument;\n\nimport java.lang.annotation.*;\n\n/**\n * 文档相关\n *
\n * 仅用于推送文档生成\n *
\n *\n * @author 渔民小镇\n * @date 2022-01-31\n * @deprecated 请使用 {@link BroadcastDocument} 代替\n */\n@Target({ElementType.TYPE})\n@Retention(RetentionPolicy.RUNTIME)\n@Documented\n@Repeatable(DocActionSends.class)\n@Deprecated\npublic @interface DocActionSend {\n /** 主路由 */\n int cmd();\n\n /** 子路由 */\n int subCmd();\n\n /** 业务对象class */\n Class dataClass();\n\n /** 推送描述 */\n String description() default \"\";\n}\n"
},
{
"path": "common/common-core/src/main/java/com/iohao/game/action/skeleton/annotation/DocActionSends.java",
"content": "/*\n * ioGame\n * Copyright (C) 2021 - present 渔民小镇 （262610965@qq.com、luoyizhu@gmail.com） . All Rights Reserved.\n * # iohao.com . 渔民小镇\n *\n * This program is free software: you can redistribute it and/or modify\n * it under the terms of the GNU Affero General Public License as\n * published by the Free Software Foundation, either version 3 of the\n * License, or (at your option) any later version.\n *\n * This program is distributed in the hope that it will be useful,\n * but WITHOUT ANY WARRANTY; without even the implied warranty of\n * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n * GNU Affero General Public License for more details.\n *\n * You should have received a copy of the GNU Affero General Public License\n * along with this program. If not, see .\n */\npackage com.iohao.game.action.skeleton.annotation;\n\nimport com.iohao.game.action.skeleton.core.doc.BroadcastDocument;\n\nimport java.lang.annotation.*;\n\n/**\n * 文档相关\n *
\n * 仅用于推送文档生成\n *
\n *\n * @author 渔民小镇\n * @date 2022-01-31\n * @deprecated 请使用 {@link BroadcastDocument} 代替\n */\n@Target({ElementType.TYPE})\n@Retention(RetentionPolicy.RUNTIME)\n@Documented\n@Deprecated\npublic @interface DocActionSends {\n DocActionSend[] value();\n}\n"
},
{
"path": "common/common-core/src/main/java/com/iohao/game/action/skeleton/annotation/ValidatedGroup.java",
"content": "/*\n * ioGame\n * Copyright (C) 2021 - present 渔民小镇 （262610965@qq.com、luoyizhu@gmail.com） . All Rights Reserved.\n * # iohao.com . 渔民小镇\n *\n * This program is free software: you can redistribute it and/or modify\n * it under the terms of the GNU Affero General Public License as\n * published by the Free Software Foundation, either version 3 of the\n * License, or (at your option) any later version.\n *\n * This program is distributed in the hope that it will be useful,\n * but WITHOUT ANY WARRANTY; without even the implied warranty of\n * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n * GNU Affero General Public License for more details.\n *\n * You should have received a copy of the GNU Affero General Public License\n * along with this program. If not, see .\n */\npackage com.iohao.game.action.skeleton.annotation;\n\nimport java.lang.annotation.*;\n\n/**\n * 验证组\n *\n * @author fangwei\n * @date 2022-09-20\n */\n@Documented\n@Retention(RetentionPolicy.RUNTIME)\n@Target({ElementType.TYPE, ElementType.METHOD, ElementType.PARAMETER})\npublic @interface ValidatedGroup {\n /**\n * 确定验证组，校验组对象的 Class\n *\n * @return 校验组对象的 Class 数组\n */\n Class[] value() default {};\n}\n"
},
{
"path": "common/common-core/src/main/java/com/iohao/game/action/skeleton/annotation/package-info.java",
"content": "/*\n * ioGame\n * Copyright (C) 2021 - present 渔民小镇 （262610965@qq.com、luoyizhu@gmail.com） . All Rights Reserved.\n * # iohao.com . 渔民小镇\n *\n * This program is free software: you can redistribute it and/or modify\n * it under the terms of the GNU Affero General Public License as\n * published by the Free Software Foundation, either version 3 of the\n * License, or (at your option) any later version.\n *\n * This program is distributed in the hope that it will be useful,\n * but WITHOUT ANY WARRANTY; without even the implied warranty of\n * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n * GNU Affero General Public License for more details.\n *\n * You should have received a copy of the GNU Affero General Public License\n * along with this program. If not, see .\n */\n/**\n * 业务框架 - 注解相关\n *\n * @author 渔民小镇\n * @date 2024-08-05\n */\npackage com.iohao.game.action.skeleton.annotation;"
},
{
"path": "common/common-core/src/main/java/com/iohao/game/action/skeleton/core/ActionCommand.java",
"content": "/*\n * ioGame\n * Copyright (C) 2021 - present 渔民小镇 （262610965@qq.com、luoyizhu@gmail.com） . All Rights Reserved.\n * # iohao.com . 渔民小镇\n *\n * This program is free software: you can redistribute it and/or modify\n * it under the terms of the GNU Affero General Public License as\n * published by the Free Software Foundation, either version 3 of the\n * License, or (at your option) any later version.\n *\n * This program is distributed in the hope that it will be useful,\n * but WITHOUT ANY WARRANTY; without even the implied warranty of\n * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n * GNU Affero General Public License for more details.\n *\n * You should have received a copy of the GNU Affero General Public License\n * along with this program. If not, see .\n */\npackage com.iohao.game.action.skeleton.core;\n\nimport com.esotericsoftware.reflectasm.ConstructorAccess;\nimport com.esotericsoftware.reflectasm.MethodAccess;\nimport com.iohao.game.action.skeleton.annotation.ValidatedGroup;\nimport com.iohao.game.action.skeleton.core.doc.ActionCommandDoc;\nimport com.iohao.game.action.skeleton.core.flow.FlowContext;\nimport com.iohao.game.action.skeleton.core.flow.parser.MethodParser;\nimport com.iohao.game.action.skeleton.core.flow.parser.MethodParsers;\nimport lombok.AccessLevel;\nimport lombok.Getter;\nimport lombok.Setter;\nimport lombok.experimental.Accessors;\nimport lombok.experimental.FieldDefaults;\n\nimport java.lang.annotation.Annotation;\nimport java.lang.reflect.Method;\nimport java.lang.reflect.Parameter;\nimport java.lang.reflect.ParameterizedType;\nimport java.util.Arrays;\nimport java.util.List;\nimport java.util.Objects;\nimport java.util.stream.Stream;\n\n/**\n * ActionCommand 命令对象，也称为 action。\n *
\n * 如果不是方法的返回值不是 List 类型，这个值会取自 paramClazz 成员属性\n * 原计划想用 Collection ，这样可以兼容 Set 之类的；但似乎这样有一点争议，先暂支持 List 把\n *
\n *\n * @return List 泛型的类型\n */\n Class getActualTypeArgumentClazz();\n }\n\n /**\n * 方法参数信息\n */\n @Getter\n public static final class ParamInfo implements MethodParamResultInfo {\n /** JSR380 空验证组 */\n static final Class[] EMPTY_GROUPS = new Class[0];\n /** 参数名 */\n final String name;\n /** 参数下标 */\n final int index;\n /** 保存 Parameter 对象 */\n final Parameter parameter;\n /** 参数类型 */\n final Class paramClazz;\n /**\n * List 泛型的类型，也称为方法返回值类型\n *
\n * 如果方法的返回值不是 List 类型，这个值会取自 paramClazz 成员属性\n * 原计划想用 Collection ，这样可以兼容 Set 之类的；但似乎这样有一点争议，先暂支持 List\n *
\n */\n final Class actualTypeArgumentClazz;\n /** true 是 list 类型 */\n final boolean list;\n\n /**\n * 实际的内置包装类型\n *
\n */\n final Class actualClazz;\n final boolean customMethodParser;\n\n private ActionMethodReturnInfo(ActionCommand.Builder builder) {\n\n this.returnTypeClazz = builder.returnTypeClazz;\n\n if (List.class.isAssignableFrom(returnTypeClazz)) {\n ParameterizedType genericReturnType = (ParameterizedType) builder.actionMethod.getGenericReturnType();\n this.actualTypeArgumentClazz = (Class) genericReturnType.getActualTypeArguments()[0];\n this.list = true;\n } else {\n this.actualTypeArgumentClazz = returnTypeClazz;\n this.list = false;\n }\n\n MethodParser methodParser = MethodParsers.getMethodParser(this);\n this.actualClazz = methodParser.getActualClazz(this);\n this.customMethodParser = methodParser.isCustomMethodParser();\n }\n\n /**\n * 方法返回值类型是否 void\n *\n * @return true 是 void\n */\n public boolean isVoid() {\n return Void.TYPE == this.returnTypeClazz;\n }\n\n @Override\n public String toString() {\n return toString(false);\n }\n\n public String toString(boolean fullName) {\n boolean isCustomList = this.list && !MethodParsers.containsKey(this.actualClazz);\n\n if (isCustomList) {\n String simpleNameReturnTypeClazz = this.returnTypeClazz.getSimpleName();\n String simpleNameActualClazz = fullName\n ? this.actualClazz.getName()\n : this.actualClazz.getSimpleName();\n\n return String.format(\"%s<%s>\", simpleNameReturnTypeClazz, simpleNameActualClazz);\n }\n\n return fullName\n ? this.actualClazz.getName()\n : this.actualClazz.getSimpleName();\n }\n }\n}\n"
},
{
"path": "common/common-core/src/main/java/com/iohao/game/action/skeleton/core/ActionCommandDocParser.java",
"content": "/*\n * ioGame\n * Copyright (C) 2021 - present 渔民小镇 （262610965@qq.com、luoyizhu@gmail.com） . All Rights Reserved.\n * # iohao.com . 渔民小镇\n *\n * This program is free software: you can redistribute it and/or modify\n * it under the terms of the GNU Affero General Public License as\n * published by the Free Software Foundation, either version 3 of the\n * License, or (at your option) any later version.\n *\n * This program is distributed in the hope that it will be useful,\n * but WITHOUT ANY WARRANTY; without even the implied warranty of\n * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n * GNU Affero General Public License for more details.\n *\n * You should have received a copy of the GNU Affero General Public License\n * along with this program. If not, see .\n */\npackage com.iohao.game.action.skeleton.core;\n\nimport com.iohao.game.action.skeleton.annotation.ActionController;\nimport com.iohao.game.action.skeleton.annotation.ActionMethod;\nimport com.iohao.game.action.skeleton.core.doc.*;\nimport lombok.AccessLevel;\nimport lombok.experimental.FieldDefaults;\nimport org.jctools.maps.NonBlockingHashMap;\n\nimport java.lang.reflect.Method;\nimport java.util.List;\nimport java.util.Map;\n\n/**\n * source doc 解析类\n *\n * @author 渔民小镇\n * @date 2022-12-09\n */\n@FieldDefaults(level = AccessLevel.PRIVATE)\nfinal class ActionCommandDocParser {\n final ActionCommandParser actionCommandParser;\n\n final Map actionCommandDocMap = new NonBlockingHashMap<>();\n\n final ActionCommandDoc emptyActionCommandDoc = new ActionCommandDoc();\n\n ActionCommandDocParser(ActionCommandParser actionCommandParser, List> controllerList, boolean parseDoc) {\n this.actionCommandParser = actionCommandParser;\n if (parseDoc) {\n this.buildSourceDoc(controllerList);\n }\n }\n\n private void buildSourceDoc(List> controllerList) {\n\n var actionCommandRegions = this.actionCommandParser.getActionCommandRegions();\n\n // java source\n Map javaClassDocInfoMap = ActionCommandDocKit.getJavaClassDocInfoMap(controllerList);\n\n this.actionCommandParser.getActionControllerStream(controllerList).parallel().forEach(controllerClazz -> {\n // java source\n JavaClassDocInfo javaClassDocInfo = javaClassDocInfoMap.get(controllerClazz.toString());\n\n // 主路由 (类上的路由)\n int cmd = controllerClazz.getAnnotation(ActionController.class).value();\n\n // 过期的方法，将来需要删除的部分\n extractedDeprecate(actionCommandRegions, controllerClazz, javaClassDocInfo, cmd);\n\n // action 文档\n ActionDoc actionDoc = IoGameDocumentHelper.ofActionDoc(cmd, controllerClazz);\n actionDoc.setJavaClassDocInfo(javaClassDocInfo);\n\n this.actionCommandParser.getMethodStream(controllerClazz).forEach(method -> {\n ActionCommandDoc actionCommandDoc = getActionCommandDoc(javaClassDocInfo, method);\n // 目标子路由 (方法上的路由)\n int subCmd = method.getAnnotation(ActionMethod.class).value();\n\n int cmdMerge = CmdKit.merge(cmd, subCmd);\n // 将数据保存在这里。\n actionCommandDocMap.put(cmdMerge, actionCommandDoc);\n actionDoc.addActionCommandDoc(actionCommandDoc);\n });\n });\n }\n\n private static void extractedDeprecate(ActionCommandRegions actionCommandRegions, Class controllerClazz, JavaClassDocInfo javaClassDocInfo, int cmd) {\n var actionCommandRegion = actionCommandRegions.getActionCommandRegion(cmd);\n actionCommandRegion.setActionControllerClazz(controllerClazz);\n actionCommandRegion.setJavaClassDocInfo(javaClassDocInfo);\n }\n\n ActionCommandDoc getActionCommandDoc(int cmd, int subCmd) {\n int cmdMerge = CmdKit.merge(cmd, subCmd);\n return actionCommandDocMap.getOrDefault(cmdMerge, emptyActionCommandDoc);\n }\n\n private ActionCommandDoc getActionCommandDoc(JavaClassDocInfo javaClassDocInfo, Method method) {\n\n if (javaClassDocInfo != null) {\n return javaClassDocInfo.createActionCommandDoc(method);\n }\n\n return new ActionCommandDoc();\n }\n}\n"
},
{
"path": "common/common-core/src/main/java/com/iohao/game/action/skeleton/core/ActionCommandFlowExecute.java",
"content": "/*\n * ioGame\n * Copyright (C) 2021 - present 渔民小镇 （262610965@qq.com、luoyizhu@gmail.com） . All Rights Reserved.\n * # iohao.com . 渔民小镇\n *\n * This program is free software: you can redistribute it and/or modify\n * it under the terms of the GNU Affero General Public License as\n * published by the Free Software Foundation, either version 3 of the\n * License, or (at your option) any later version.\n *\n * This program is distributed in the hope that it will be useful,\n * but WITHOUT ANY WARRANTY; without even the implied warranty of\n * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n * GNU Affero General Public License for more details.\n *\n * You should have received a copy of the GNU Affero General Public License\n * along with this program. If not, see .\n */\npackage com.iohao.game.action.skeleton.core;\n\nimport com.iohao.game.action.skeleton.core.flow.FlowContext;\n\n/**\n * 命令流程执行器\n *\n * @author 渔民小镇\n * @date 2021-12-20\n */\npublic interface ActionCommandFlowExecute {\n /**\n * 模板方法模式：\n *
\n *\n * @param flowContext FlowContext\n */\n void execute(FlowContext flowContext);\n\n static ActionCommandFlowExecute defaultInstance() {\n return DefaultActionCommandFlowExecute.me();\n }\n}\n"
},
{
"path": "common/common-core/src/main/java/com/iohao/game/action/skeleton/core/ActionCommandHandler.java",
"content": "/*\n * ioGame\n * Copyright (C) 2021 - present 渔民小镇 （262610965@qq.com、luoyizhu@gmail.com） . All Rights Reserved.\n * # iohao.com . 渔民小镇\n *\n * This program is free software: you can redistribute it and/or modify\n * it under the terms of the GNU Affero General Public License as\n * published by the Free Software Foundation, either version 3 of the\n * License, or (at your option) any later version.\n *\n * This program is distributed in the hope that it will be useful,\n * but WITHOUT ANY WARRANTY; without even the implied warranty of\n * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n * GNU Affero General Public License for more details.\n *\n * You should have received a copy of the GNU Affero General Public License\n * along with this program. If not, see .\n */\npackage com.iohao.game.action.skeleton.core;\n\nimport com.iohao.game.action.skeleton.core.flow.FlowContext;\nimport com.iohao.game.action.skeleton.core.flow.FlowContextKit;\nimport lombok.extern.slf4j.Slf4j;\n\n/**\n * 该handler用于执行 {@link ActionCommand} 对象\n *\n * @author 渔民小镇\n * @date 2021-12-12\n */\n@Slf4j\nclass ActionCommandHandler implements Handler {\n\n @Override\n public boolean handler(final FlowContext flowContext) {\n\n try {\n // 设置 flowContext 的一些属性\n this.settingFlowContext(flowContext);\n // actionCommand 命令流程执行器\n ActionCommandFlowExecute.defaultInstance().execute(flowContext);\n } catch (Throwable e) {\n log.error(e.getMessage(), e);\n return false;\n }\n\n return true;\n }\n\n protected void settingFlowContext(FlowContext flowContext) {\n /*\n * 做一些兼容，这部分逻辑在 RequestMessageClientProcessor 已经设置过一次，\n * 这里做兼容的目的有两个：\n * 1 防止开发者将 RequestMessageClientProcessor 移除，并做了相关的自定义。\n * 2 业务框架可以单独做测试\n */\n FlowContextKit.employ(flowContext);\n\n // 业务框架\n BarSkeleton barSkeleton = flowContext.getBarSkeleton();\n\n // 参数解析器\n var paramParser = barSkeleton.getActionMethodParamParser();\n // 得到业务方法的参数列表，并验证\n var params = paramParser.listParam(flowContext);\n // 业务方法参数 save to flowContext\n flowContext.setMethodParams(params);\n }\n}\n"
},
{
"path": "common/common-core/src/main/java/com/iohao/game/action/skeleton/core/ActionCommandParser.java",
"content": "/*\n * ioGame\n * Copyright (C) 2021 - present 渔民小镇 （262610965@qq.com、luoyizhu@gmail.com） . All Rights Reserved.\n * # iohao.com . 渔民小镇\n *\n * This program is free software: you can redistribute it and/or modify\n * it under the terms of the GNU Affero General Public License as\n * published by the Free Software Foundation, either version 3 of the\n * License, or (at your option) any later version.\n *\n * This program is distributed in the hope that it will be useful,\n * but WITHOUT ANY WARRANTY; without even the implied warranty of\n * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n * GNU Affero General Public License for more details.\n *\n * You should have received a copy of the GNU Affero General Public License\n * along with this program. If not, see .\n */\npackage com.iohao.game.action.skeleton.core;\n\n\nimport com.esotericsoftware.reflectasm.ConstructorAccess;\nimport com.esotericsoftware.reflectasm.MethodAccess;\nimport com.iohao.game.action.skeleton.annotation.ActionController;\nimport com.iohao.game.action.skeleton.annotation.ActionMethod;\nimport com.iohao.game.action.skeleton.core.action.parser.ActionParserContext;\nimport com.iohao.game.action.skeleton.core.action.parser.ActionParserListener;\nimport com.iohao.game.action.skeleton.core.codec.ProtoDataCodec;\nimport com.iohao.game.action.skeleton.core.doc.ActionCommandDoc;\nimport com.iohao.game.action.skeleton.core.doc.ActionDoc;\nimport com.iohao.game.action.skeleton.core.doc.IoGameDocumentHelper;\nimport com.iohao.game.action.skeleton.toy.IoGameBanner;\nimport com.iohao.game.common.kit.StrKit;\nimport lombok.AccessLevel;\nimport lombok.Getter;\nimport lombok.Setter;\nimport lombok.experimental.Accessors;\nimport lombok.experimental.FieldDefaults;\nimport org.jctools.maps.NonBlockingHashMap;\n\nimport java.lang.reflect.Method;\nimport java.lang.reflect.Modifier;\nimport java.lang.reflect.Parameter;\nimport java.util.*;\nimport java.util.stream.Stream;\n\n/**\n * action 命令对象解析器，将 action 类下的业务方法解析为 actionCommand\n *
\n *\n * @author 渔民小镇\n * @date 2022-05-15\n */\n@Getter\n@Setter\n@FieldDefaults(level = AccessLevel.PACKAGE)\npublic final class ActionCommandRegion {\n final int cmd;\n /** actionControllerClazz */\n Class actionControllerClazz;\n /** actionControllerClazz 的源文件信息 */\n JavaClassDocInfo javaClassDocInfo;\n /**\n *
\n * key: subCmd\n * value: ActionCommand\n *
\n */\n Map subActionCommandMap = new NonBlockingHashMap<>();\n\n public ActionCommandRegion(int cmd) {\n this.cmd = cmd;\n }\n\n public boolean containsKey(int subCmd) {\n return this.subActionCommandMap.containsKey(subCmd);\n }\n\n public void add(ActionCommand subActionCommand) {\n var cmdInfo = subActionCommand.getCmdInfo();\n\n int subCmd = cmdInfo.getSubCmd();\n\n this.subActionCommandMap.put(subCmd, subActionCommand);\n }\n\n /**\n * 得到子路由最大值\n *\n * @return 子路由最大值\n */\n public int getMaxSubCmd() {\n return subActionCommandMap\n .keySet()\n .stream()\n .max(Integer::compareTo)\n .orElse(0)\n ;\n }\n\n public Collection values() {\n return this.subActionCommandMap.values();\n }\n\n /**\n * 将子路由列表转为数组\n *\n * @return array\n */\n public ActionCommand[] arrayActionCommand() {\n // 子路由最大值\n int subCmdMax = this.getMaxSubCmd() + 1;\n ActionCommand[] subBehaviors = new ActionCommand[subCmdMax];\n\n for (Map.Entry subEntry : subActionCommandMap.entrySet()) {\n subBehaviors[subEntry.getKey()] = subEntry.getValue();\n }\n\n return subBehaviors;\n }\n}\n"
},
{
"path": "common/common-core/src/main/java/com/iohao/game/action/skeleton/core/ActionCommandRegionGlobalCheckKit.java",
"content": "/*\n * ioGame\n * Copyright (C) 2021 - present 渔民小镇 （262610965@qq.com、luoyizhu@gmail.com） . All Rights Reserved.\n * # iohao.com . 渔民小镇\n *\n * This program is free software: you can redistribute it and/or modify\n * it under the terms of the GNU Affero General Public License as\n * published by the Free Software Foundation, either version 3 of the\n * License, or (at your option) any later version.\n *\n * This program is distributed in the hope that it will be useful,\n * but WITHOUT ANY WARRANTY; without even the implied warranty of\n * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n * GNU Affero General Public License for more details.\n *\n * You should have received a copy of the GNU Affero General Public License\n * along with this program. If not, see .\n */\npackage com.iohao.game.action.skeleton.core;\n\nimport com.iohao.game.common.kit.StrKit;\nimport com.iohao.game.common.kit.exception.ThrowKit;\nimport lombok.experimental.UtilityClass;\n\nimport java.util.HashMap;\nimport java.util.Map;\n\n/**\n * 全局重复路由检测工具\n *
\n *\n * @author 渔民小镇\n * @date 2022-07-31\n */\n@UtilityClass\npublic class ActionCommandRegionGlobalCheckKit {\n\n Map map = new HashMap<>();\n\n public void putActionCommandRegions(String key, ActionCommandRegions actionCommandRegions) {\n\n if (map.containsKey(key)) {\n return;\n }\n\n map.put(key, actionCommandRegions);\n }\n\n /**\n * 全局重复路由检测\n */\n public void checkGlobalExistSubCmd() {\n\n Map cmdMap = new HashMap<>(100);\n\n // 多服单进程下的所有业务框架的命令域管理器\n var actionCommandRegionList = map\n .values()\n .parallelStream()\n .flatMap(ActionCommandRegions::streamActionCommandRegion)\n .toList();\n\n for (ActionCommandRegion actionCommandRegion : actionCommandRegionList) {\n // 命令域下的路由 action\n for (ActionCommand actionCommand : actionCommandRegion.values()) {\n // 路由信息\n CmdInfo cmdInfo = actionCommand.getCmdInfo();\n\n int cmdMerge = cmdInfo.getCmdMerge();\n // 如果是重复路由，就抛异常\n if (cmdMap.containsKey(cmdMerge)) {\n\n String template = \"\"\"\n 全局重复路由检测，使用了相同的路由，或者多个业务框架中，加载了相同的 action\n cmd:【{}】下已经存在方法编号 subCmd:【{}】 .请查看: {}\n \"\"\";\n\n String message = StrKit.format(template,\n actionCommandRegion.cmd,\n cmdInfo.getSubCmd(),\n actionCommand.getActionControllerClazz()\n );\n\n ThrowKit.ofRuntimeException(message);\n }\n\n cmdMap.put(cmdMerge, actionCommand);\n }\n }\n\n // 清空数据，检测完了\n map.clear();\n cmdMap.clear();\n }\n}\n"
},
{
"path": "common/common-core/src/main/java/com/iohao/game/action/skeleton/core/ActionCommandRegions.java",
"content": "/*\n * ioGame\n * Copyright (C) 2021 - present 渔民小镇 （262610965@qq.com、luoyizhu@gmail.com） . All Rights Reserved.\n * # iohao.com . 渔民小镇\n *\n * This program is free software: you can redistribute it and/or modify\n * it under the terms of the GNU Affero General Public License as\n * published by the Free Software Foundation, either version 3 of the\n * License, or (at your option) any later version.\n *\n * This program is distributed in the hope that it will be useful,\n * but WITHOUT ANY WARRANTY; without even the implied warranty of\n * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n * GNU Affero General Public License for more details.\n *\n * You should have received a copy of the GNU Affero General Public License\n * along with this program. If not, see .\n */\npackage com.iohao.game.action.skeleton.core;\n\nimport com.iohao.game.action.skeleton.i18n.Bundle;\nimport com.iohao.game.action.skeleton.i18n.MessageKey;\nimport com.iohao.game.action.skeleton.toy.IoGameBanner;\nimport com.iohao.game.common.kit.MoreKit;\nimport lombok.AccessLevel;\nimport lombok.Getter;\nimport lombok.experimental.FieldDefaults;\nimport org.jctools.maps.NonBlockingHashMap;\n\nimport java.util.List;\nimport java.util.Map;\nimport java.util.Objects;\nimport java.util.function.Function;\nimport java.util.stream.Collectors;\nimport java.util.stream.Stream;\n\n/**\n * 命令域 管理器\n *
\n * 管理命令域\n *\n * 路由与子路由的关系维护\n *
\n *\n * @author 渔民小镇\n * @date 2022-05-15\n */\n@Getter\n@FieldDefaults(level = AccessLevel.PACKAGE)\npublic final class ActionCommandRegions {\n private static final ActionCommand[][] EMPTY = new ActionCommand[0][0];\n\n /**\n * action map\n *
\n * key : cmd\n * value : subCmd region\n *
\n */\n final Map regionMap = new NonBlockingHashMap<>();\n\n /**\n * action 数组. 下标对应 cmd\n *
\n *\n * @param barSkeletonSetting config\n * @return 二维数组\n */\n private ActionCommand[][] convertArray(BarSkeletonSetting barSkeletonSetting) {\n\n if (this.regionMap.isEmpty()) {\n return EMPTY;\n }\n\n // 获取主路由最大值\n int max = getMaxCmd(barSkeletonSetting);\n\n var behaviors = new ActionCommand[max][1];\n\n this.regionMap.keySet().forEach(cmd -> {\n var actionCommandRegion = this.regionMap.get(cmd);\n\n behaviors[cmd] = actionCommandRegion.arrayActionCommand();\n });\n\n return behaviors;\n }\n\n private int getMaxCmd(BarSkeletonSetting barSkeletonSetting) {\n // 获取最大的路由数字 并且+1\n int max = this.regionMap\n .keySet()\n .stream()\n .max(Integer::compareTo)\n .orElse(0) + 1;\n\n if (max > barSkeletonSetting.getCmdMaxLen()) {\n /*\n * %s exceeds the maximum default value.\n * Please set the capacity manually if necessary.\n * Default maximum capacity %d, current capacity %d\n */\n var info = Bundle.getMessage(MessageKey.cmdMergeLimit).formatted(\n \"cmd\", barSkeletonSetting.getCmdMaxLen(), max\n );\n\n IoGameBanner.me().ofRuntimeException(info);\n }\n\n // subCmd\n for (ActionCommandRegion actionCommandRegion : this.regionMap.values()) {\n\n int subCmdMax = actionCommandRegion.getMaxSubCmd() + 1;\n\n if (subCmdMax > barSkeletonSetting.getSubCmdMaxLen()) {\n var info = Bundle.getMessage(MessageKey.cmdMergeLimit).formatted(\n \"subCmd\", barSkeletonSetting.getSubCmdMaxLen(), subCmdMax\n );\n\n IoGameBanner.me().ofRuntimeException(info);\n }\n }\n\n return max;\n }\n}\n"
},
{
"path": "common/common-core/src/main/java/com/iohao/game/action/skeleton/core/ActionFactoryBean.java",
"content": "/*\n * ioGame\n * Copyright (C) 2021 - present 渔民小镇 （262610965@qq.com、luoyizhu@gmail.com） . All Rights Reserved.\n * # iohao.com . 渔民小镇\n *\n * This program is free software: you can redistribute it and/or modify\n * it under the terms of the GNU Affero General Public License as\n * published by the Free Software Foundation, either version 3 of the\n * License, or (at your option) any later version.\n *\n * This program is distributed in the hope that it will be useful,\n * but WITHOUT ANY WARRANTY; without even the implied warranty of\n * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n * GNU Affero General Public License for more details.\n *\n * You should have received a copy of the GNU Affero General Public License\n * along with this program. If not, see .\n */\npackage com.iohao.game.action.skeleton.core;\n\nimport com.iohao.game.action.skeleton.annotation.ActionController;\n\n/**\n * action 类对象创建工厂，负责创建 action 类的实例化对象\n *\n * @param t\n * @author 渔民小镇\n * @date 2021-12-20\n */\npublic interface ActionFactoryBean {\n /**\n * 获取 action 类的对象\n *
\n *\n * @param actionCommand actionCommand\n * @return action 类的实例化对象\n */\n T getBean(ActionCommand actionCommand);\n\n /**\n * 通过 action class 得到对应 bean\n *\n * @param actionControllerClazz action class\n * @return action 类的实例化对象\n */\n default T getBean(Class actionControllerClazz) {\n return null;\n }\n}\n"
},
{
"path": "common/common-core/src/main/java/com/iohao/game/action/skeleton/core/ActionParserListenerAbout.java",
"content": "/*\n * ioGame\n * Copyright (C) 2021 - present 渔民小镇 （262610965@qq.com、luoyizhu@gmail.com） . All Rights Reserved.\n * # iohao.com . 渔民小镇\n *\n * This program is free software: you can redistribute it and/or modify\n * it under the terms of the GNU Affero General Public License as\n * published by the Free Software Foundation, either version 3 of the\n * License, or (at your option) any later version.\n *\n * This program is distributed in the hope that it will be useful,\n * but WITHOUT ANY WARRANTY; without even the implied warranty of\n * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n * GNU Affero General Public License for more details.\n *\n * You should have received a copy of the GNU Affero General Public License\n * along with this program. If not, see .\n */\npackage com.iohao.game.action.skeleton.core;\n\nimport com.baidu.bjf.remoting.protobuf.annotation.ProtobufClass;\nimport com.iohao.game.action.skeleton.core.action.parser.ActionParserContext;\nimport com.iohao.game.action.skeleton.core.action.parser.ActionParserListener;\nimport com.iohao.game.action.skeleton.i18n.Bundle;\nimport com.iohao.game.action.skeleton.i18n.MessageKey;\nimport com.iohao.game.action.skeleton.protocol.wrapper.*;\nimport com.iohao.game.common.kit.ProtoKit;\nimport lombok.AccessLevel;\nimport lombok.experimental.FieldDefaults;\nimport lombok.extern.slf4j.Slf4j;\nimport org.jctools.maps.NonBlockingHashSet;\n\nimport java.util.Objects;\nimport java.util.Optional;\nimport java.util.Set;\nimport java.util.function.Predicate;\n\n/**\n * Prepared action proto\n *\n * @author 渔民小镇\n * @date 2024-05-01\n * @since 21.7\n */\n@FieldDefaults(level = AccessLevel.PRIVATE)\nfinal class ProtobufActionParserListener implements ActionParserListener {\n static final Set> protoSet = new NonBlockingHashSet<>();\n\n static {\n // create a protobuf proxy class\n ProtoKit.create(ByteValueList.class);\n\n ProtoKit.create(IntValue.class);\n ProtoKit.create(IntValueList.class);\n\n ProtoKit.create(BoolValue.class);\n ProtoKit.create(BoolValueList.class);\n\n ProtoKit.create(LongValue.class);\n ProtoKit.create(LongValueList.class);\n\n ProtoKit.create(StringValue.class);\n ProtoKit.create(StringValueList.class);\n }\n\n @Override\n public void onActionCommand(ActionParserContext context) {\n // 添加了 ProtobufClass 注解的类\n Predicate> protobufClassPredicate = c -> Objects.nonNull(c.getAnnotation(ProtobufClass.class));\n collect(context, protobufClassPredicate, protoSet);\n }\n\n static void collect(ActionParserContext context, Predicate> protobufClassPredicate, Set> protoSet) {\n // 将 action 的方法参数与返回值添加了 ProtobufClass 注解的类信息收集到 protoSet 中\n ActionCommand actionCommand = context.getActionCommand();\n // action 参数相关\n actionCommand.streamParamInfo()\n // 只处理业务参数\n .filter(ActionCommand.ParamInfo::isBizData)\n // 得到参数类型\n .map(ActionCommand.ParamInfo::getActualTypeArgumentClazz)\n // 协议碎片类型不做处理\n .filter(clazz -> !WrapperKit.isWrapper(clazz))\n // 添加了 ProtobufClass 注解的类\n .filter(protobufClassPredicate)\n .forEach(protoSet::add);\n\n // action 返回值相关\n Optional\n .ofNullable(actionCommand.getActionMethodReturnInfo())\n // void 不处理\n .filter(actionMethodReturnInfo -> !actionMethodReturnInfo.isVoid())\n .map(ActionCommand.ActionMethodReturnInfo::getActualTypeArgumentClazz)\n // 协议碎片类型不做处理\n .filter(clazz -> !WrapperKit.isWrapper(clazz))\n // 添加了 ProtobufClass 注解的类\n .filter(protobufClassPredicate)\n .ifPresent(protoSet::add);\n }\n\n @Override\n public void onAfter(BarSkeleton barSkeleton) {\n protoSet.forEach(ProtoKit::create);\n }\n}\n\n/**\n * proto 协议类型添检测\n *\n * @author 渔民小镇\n * @date 2024-05-02\n * @since 21.7\n */\n@Slf4j\nfinal class ProtobufCheckActionParserListener implements ActionParserListener {\n static final Set> protoSet = new NonBlockingHashSet<>();\n\n @Override\n public void onActionCommand(ActionParserContext context) {\n // 添加了 ProtobufClass 注解的类\n Predicate> protobufClassPredicate = c -> c.getAnnotation(ProtobufClass.class) == null;\n ProtobufActionParserListener.collect(context, protobufClassPredicate, protoSet);\n }\n\n @Override\n public void onAfter(BarSkeleton barSkeleton) {\n if (protoSet.isEmpty()) {\n return;\n }\n\n log.error(Bundle.getMessage(MessageKey.protobufAnnotationCheck));\n for (Class protoClass : protoSet) {\n log.error(protoClass.toString());\n }\n }\n}"
},
{
"path": "common/common-core/src/main/java/com/iohao/game/action/skeleton/core/ActionSend.java",
"content": "/*\n * ioGame\n * Copyright (C) 2021 - present 渔民小镇 （262610965@qq.com、luoyizhu@gmail.com） . All Rights Reserved.\n * # iohao.com . 渔民小镇\n *\n * This program is free software: you can redistribute it and/or modify\n * it under the terms of the GNU Affero General Public License as\n * published by the Free Software Foundation, either version 3 of the\n * License, or (at your option) any later version.\n *\n * This program is distributed in the hope that it will be useful,\n * but WITHOUT ANY WARRANTY; without even the implied warranty of\n * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n * GNU Affero General Public License for more details.\n *\n * You should have received a copy of the GNU Affero General Public License\n * along with this program. If not, see .\n */\npackage com.iohao.game.action.skeleton.core;\n\n/**\n * @author 渔民小镇\n * @date 2022-01-30\n */\n@Deprecated\npublic interface ActionSend {\n\n /**\n * 合并路由\n *\n * @return 合并路由\n * @see CmdKit#merge(int, int)\n */\n int getCmdMerge();\n}\n"
},
{
"path": "common/common-core/src/main/java/com/iohao/game/action/skeleton/core/BarMessageKit.java",
"content": "/*\n * ioGame\n * Copyright (C) 2021 - present 渔民小镇 （262610965@qq.com、luoyizhu@gmail.com） . All Rights Reserved.\n * # iohao.com . 渔民小镇\n *\n * This program is free software: you can redistribute it and/or modify\n * it under the terms of the GNU Affero General Public License as\n * published by the Free Software Foundation, either version 3 of the\n * License, or (at your option) any later version.\n *\n * This program is distributed in the hope that it will be useful,\n * but WITHOUT ANY WARRANTY; without even the implied warranty of\n * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n * GNU Affero General Public License for more details.\n *\n * You should have received a copy of the GNU Affero General Public License\n * along with this program. If not, see .\n */\npackage com.iohao.game.action.skeleton.core;\n\nimport com.iohao.game.action.skeleton.protocol.HeadMetadata;\nimport com.iohao.game.action.skeleton.protocol.RequestMessage;\nimport com.iohao.game.action.skeleton.protocol.ResponseMessage;\nimport lombok.experimental.UtilityClass;\n\nimport java.util.Objects;\n\n/**\n * 创建 RequestMessage，ResponseMessage 相关内部消息的工具类\n *\n * @author 渔民小镇\n * @date 2022-06-07\n * @see RequestMessage\n * @see ResponseMessage\n */\n@UtilityClass\npublic class BarMessageKit {\n public RequestMessage createRequestMessage(CmdInfo cmdInfo) {\n return createRequestMessage(cmdInfo, null);\n }\n\n /**\n * 创建 RequestMessage\n *\n * @param cmdInfo 路由\n * @param data 业务数据\n * @return RequestMessage\n */\n public RequestMessage createRequestMessage(CmdInfo cmdInfo, Object data) {\n\n RequestMessage requestMessage = new RequestMessage();\n\n employ(requestMessage, cmdInfo, data);\n\n return requestMessage;\n }\n\n /**\n * 将路由、业务数据设置到 RequestMessage 中\n *\n * @param requestMessage RequestMessage\n * @param cmdInfo 路由\n * @param data 业务数据\n */\n public void employ(RequestMessage requestMessage, CmdInfo cmdInfo, Object data) {\n\n var headMetadata = new HeadMetadata()\n .setCmdInfo(cmdInfo)\n // 请求命令类型: 0 心跳，1 业务; see ExternalMessageCmdCode\n .setCmdCode(1);\n\n requestMessage.setHeadMetadata(headMetadata);\n\n if (Objects.nonNull(data)) {\n requestMessage.setData(data);\n }\n }\n\n /**\n * 创建响应对象\n *\n * @param cmdInfo 路由地址\n * @return ResponseMessage\n */\n public ResponseMessage createResponseMessage(CmdInfo cmdInfo) {\n\n ResponseMessage responseMessage = new ResponseMessage();\n // 元信息 路由地址\n responseMessage.setHeadMetadata(new HeadMetadata().setCmdInfo(cmdInfo));\n\n return responseMessage;\n }\n\n /**\n * 创建响应对象\n *\n * @param cmdInfo 路由地址\n * @param bizData 业务数据\n * @return ResponseMessage\n */\n public ResponseMessage createResponseMessage(CmdInfo cmdInfo, Object bizData) {\n\n Objects.requireNonNull(bizData);\n\n ResponseMessage responseMessage = createResponseMessage(cmdInfo);\n // 业务数据\n responseMessage.setData(bizData);\n\n return responseMessage;\n }\n}\n"
},
{
"path": "common/common-core/src/main/java/com/iohao/game/action/skeleton/core/BarSkeleton.java",
"content": "/*\n * ioGame\n * Copyright (C) 2021 - present 渔民小镇 （262610965@qq.com、luoyizhu@gmail.com） . All Rights Reserved.\n * # iohao.com . 渔民小镇\n *\n * This program is free software: you can redistribute it and/or modify\n * it under the terms of the GNU Affero General Public License as\n * published by the Free Software Foundation, either version 3 of the\n * License, or (at your option) any later version.\n *\n * This program is distributed in the hope that it will be useful,\n * but WITHOUT ANY WARRANTY; without even the implied warranty of\n * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n * GNU Affero General Public License for more details.\n *\n * You should have received a copy of the GNU Affero General Public License\n * along with this program. If not, see .\n */\npackage com.iohao.game.action.skeleton.core;\n\nimport com.iohao.game.action.skeleton.core.flow.*;\nimport com.iohao.game.action.skeleton.core.runner.Runners;\nimport com.iohao.game.common.kit.attr.AttrOptionDynamic;\nimport com.iohao.game.common.kit.attr.AttrOptions;\nimport com.iohao.game.common.kit.concurrent.executor.ExecutorRegion;\nimport lombok.AccessLevel;\nimport lombok.Getter;\nimport lombok.Setter;\nimport lombok.experimental.Accessors;\n\n\n/**\n * 整个核心的骨架.积木骷髅 (业务框架)\n *
![\"JDK](\"https://img.shields.io/badge/JDK-21-success.svg\"){kind=icon}
\n\t\n\t![\"AGPL3.0\"](\"https://img.shields.io/:license-AGPL3.0-blue.svg\")
\n\t\n\t
\n\t\n\t\n\t\t![\"github](\"https://img.shields.io/github/stars/iohao/ioGame.svg?logo=github\")
\n\t\n