Skip to content

Assambra/Free-MMORPG

BranchesTags

Repository files navigation

Contributors Forks Stargazers Issues MIT License

Free-MMORPG

Free-MMORPG screenshot

Table of Contents

Foreword

This project utilizes free resources for both server and client technology. Without these, the project likely wouldn't have been possible, so I extend my special thanks to the team at Young Monkeys for their excellent foundational work, particularly for the EzyFox Server framework, and for sharing it with the community. Also, special thanks to all the contributors to the UMA project and their outstanding Unity Multipurpose Avatar System. For the ocean, we use the Crest Ocean System, which, in my personal opinion, is the best available ocean system for Unity. As a terrain generation tool, we use MapMagic 2 (the free version from the Asset Store). If you need more features, check out the paid version of MM2. Please check out our Resources Section to see what technologies we use and consider supporting their projects in some way, such as through donations or code contributions, to help these talented individuals continue doing what they love: writing great code and developing fantastic frameworks.

For the game client we are using Unity as game engine.

(back to top)

Key Features

  • Area of Interest System on the Unity-Server
    • Capability to send spawn or despawn commands to the Unity Client player based on range
    • Each entity has a NearbyPlayer list and sends position updates only to players in this list
  • Entity-Driven Architecture
    • The core philosophy is that everything is an entity. Players, NPCs, buildings, and effects all follow the same base entity approach and are extended only where needed.
    • An entity is the common base type and can represent a player, NPC, building, or effect. Currently, Player is implemented and working, while NPC, Building, and Effect support is still in progress.
    • Each spawned entity on the Unity Client is managed through the client entity system and can be initialized from shared entity data.
    • Dynamic entities can use network-driven transform updates, while static entities are intended for non-moving world objects.
    • If the Unity Server sends a spawn or despawn command to the client, the entity is instantiated or destroyed accordingly and added to or removed from the client entity list.
    • Player spawning is currently the fully implemented path, including local player setup, remote player handling, and UMA-based character creation.
    • 3D model-based non-UMA entities and effect entities are not fully implemented or tested yet.
  • Master Server
    • Extended EzyFox Server capabilities to spawn Unity-based server instances for each room
    • Unified Unity-Server project for managing all room-specific game logic
    • Consistent use of Unity Engine for both client and server to streamline development
    • Centralized user management, database handling, and request forwarding via EzyFox Server
    • Seamless communication flow between Unity-Client, Master-Server, and Unity-Servers
  • Account Management
    • Create a new account
    • Account activation, sending activation code via email, login checks if account activated if not needed to insert the code, resend code possible.
    • Login
    • Forgot password function, sending new password to a given username / e-mail address
    • Forgot username function, sending the username to a given e-mail address
    • SSL encryption for creating accounts this is feature from the EzyFox Server framework EzyFox Server SSL
  • Email
    • Sending e-mails via smtp, with different authentication protocols SSL, TLS or no authentication
    • Easy to create a new custom mails with our interface MailBody
    • HTML based email templates, you can also use your own variables
  • Character Creation
    • Creating a new character
    • Modifiable character model thanks to UMA, modifying the look of the character with sliders
    • Colorize character, skin, hairs underwear.
    • Change Hair, Beard Eyebrows, Underwear
    • Save the character server/database
  • Character Selection
    • Character selection with all available characters
    • The option to delete a character
  • Character Movement
    • Server authoritative movement with client-side prediction, server reconciliation and interpolation for smooth local and remote movement
    • Server-driven motion and animation syncing based on movement and motion states
    • Idle-based client-server traffic reduction to stop unnecessary input and motion updates while entities are standing still
  • Scene and UI Management, from our Module-GameManager
    • We use one persistent Scene all other scene will be load additive/async the last one will unloaded async.
    • For each scene we can create a scene asset (ScriptableObject) that holds a List of SceneUISet also a asset (ScriptableObject)
    • A SceneUISet (ScriptableObject) containing all the UIElement prefabs as a Set in an Array that we want to instantiate in the Scene. You can also add multiple sets per scene.
    • All Scene UIs will automatically be instantiated for the Scene and last Scene UIs will be destroyed. A check if the next scene have the same SceneUISets, then it don't have to be destroyed or instantiated the UI`s.
  • Mouse Handler, from our Module-MouseHandler
    • Gives the user a visual feedback what is currently under the mouse cursor and changes the cursor look (2D UI) with Graphic Raycaster
    • Enhanced IsOverUIElement - This stores when you press the left mouse button whether you was over a UI element or not and saves the state until you release the mouse button.
  • CameraController, from our Module-CameraController
    • The camera can orbit around the character on LMB, same on RMB but turn the target object.
    • A lot of options to fine tune the camera behaviour
    • Planed: Camera collision, more smoothing of the camera motions, distance and orbit
  • Popup System
    • Create your own popups for different use-cases
  • World Scene
    • Nice looking Island surrounded by an ocean

(back to top)

Playable Demo

We provide a playable demo where you can play the latest release, check what Free-MMORPG can do, or test and send bug reports. You can find it here: Get Latest. Only the latest release has a playable demo, provided as a .zip file. This client will connect to our game server.

(back to top)

Getting Started

Get the project from github

Clone the repository:

git clone git@github.com:Assambra/Free-MMORPG.git

Download and import EzyFox Server CSharp Client Unity

Download and extract the following file: ezyfox-server-csharp-client-1.1.6-unity.zip.

Perform the following steps for both Unity projects: Free-Client and Free-Server:

  1. Open the project in the Unity Editor.
  2. Select all folders and files from the extracted folder ezyfox-server-csharp-client-1.1.6-unity/ezyfox-server-csharp-client-1.1.6-unity and drag them into the folder /Assets/Plugins/ezyfox-server-csharp-client-1.1.6-unity/ of your opened Unity project.

Needed projects from GitHub

Crest Ocean System

  1. Get Crest Ocean System Download and extract the following file: crest-4.21.3.zip.

  2. Install Crest Ocean System

  3. Open the Unity-Client project in the Unity Editor. Unzip and select all folders and filesthe second crest folder into Unity: crest-4.21.3/crest-4.21.3/crest/Assets/Crest/Crest.

  4. Select all folders and files from the extracted folder crest-4.21.3/crest-4.21.3/crest/Assets/Crest/Crest/ and drag them into the folder /Assets/Crest/ of your opened Unity project.

Needed Unity packages from the Unity Asset Store

MapMagic 2

Go to the Unity Asset Store and get the free asset: MapMagic 2.

After acquiring the asset:

  1. Open both projects (Free-Client and Free-Server) in the Unity Editor.
  2. Open the Package Manager (Window -> Package Manager) and select Packages: My Assets.
  3. Download and import MapMagic 2 into both projects.

UMA 2

Please use our modified version of UMA: UMA 2.13 Beta 1-modified.rar.

Steps to use it:

  1. Download and extract the .rar file.
  2. Drag the folder UMA directly into Free-Client/Assets in the Unity Editor.

Alternatively, get the free asset from the Unity Asset Store: UMA 2.

After importing UMA 2 into the project, you must add Assembly Definition References:

  1. Navigate to Assets/UMA/Core/UMA_Core.
  2. In the Inspector, add references for Unity.Mathematics, Unity.Burst, and Unity.Collections.

Free-Server

Build the Free-Server

Open the Unity-Server project in Unity. Open the Build Settings: (File -> Build Settings). The master server can handle the following three types of builds:

  • Windows, Mac, Linux
  • Dedicated Server - Windows
  • Dedicated Server - Linux

Select Windows, Mac, Linux or Dedicated Server as the Platform. Then, under Target Platform, choose your platform (Windows or Linux) and build the project.

Setup Server Executables Path

Open the master-server project in your IDE. Edit the following file:
master-server/master-server-app-api/src/main/resources/application.properties.

Add the path to your server executables from the previous step where you saved them. For example:
D:/Game Builds/Free-Server/Free-Server.exe.

Master-Server

Setup Database

  1. Install MongoDB.
  2. Open your Mongo shell (mongosh).
  3. Create your database:
use free
  1. Create a new user and password, and give it access to the created database:
db.createUser({
  user: "root", 
  pwd: "123456", 
  roles: [{role: "readWrite", db: "free"}]
})
  1. Copy the content of the repository file MongoDB_Database.js and paste it directly into mongosh.

File location: MongoDB_Database.js

This file is located in the root of the repository and contains all required collections, indexes, and seed data.

On a remote Linux server without a graphical environment, the easiest way is:

mongosh
use free

Then copy and paste the full content of Free-MMORPG/MongoDB_Database.js directly into the shell.

  1. Add to the following configuration file if not exist:

File location: master.server/master-server-common/src/main/resources/master-server-common-config.properties

  1. Insert the following values into your configuration file and modify them as needed:
database.mongo.uri=mongodb://root:123456@127.0.0.1:27017/free
database.mongo.database=free
database.mongo.collection.naming.case=UNDERSCORE
database.mongo.collection.naming.ignored_suffix=Entity

Example credentials:

  • User: root
  • Password: 123456
  • Database: free

Setup Mail

Enable or disable server-side email sending via SMTP.

If you do not have a mail server or mail provider that supports sending emails via SMTP, or if you do not wish to send emails (e.g., for local development), locate the following file:

File location:
Free-MMORPG/master-server/master-server-common/src/main/resources/master-server-common-config.properties

Set the value to false:

server.can_send_mail=false;

Important: When server.can_send_mail is set to false, only log messages are generated on the server side. This is primarily intended for local development. For production environments, email functionality should be properly configured to enable features like "Forgot Password," "Forgot Username," and "Account Activation."

Setup Mail Values

For production environments, configure email functionality in the same configuration file used for the database settings:

File location:
Free-MMORPG/master-server/master-server-common/src/main/resources/master-server-common-config.properties

Modify the following settings:

mail.host=mail.example.com
mail.port.tls=587
mail.port.ssl=465
mail.authentication=true
mail.username=account@example.com
mail.password=123456
mail.tls=true
mail.ssl=false
mail.mail.address=account@example.com
mail.mail.sender.name=YourCompany Account Management
mail.use.reply.address=false
mail.mail.reply.address=account@example.com
mail.charset=UTF-8
mail.content.type.primary=text/HTML
mail.content.type.sub=charset=UTF-8
mail.format=flowed
mail.content.transfer.encoding=8bit

Hint:
Do not set both mail.tls and mail.ssl to true simultaneously. Only one should be set to true to avoid conflicts.

Deploy Master-Server

Download Server

Download the EzyFox Server: ezyfox-server-full-1.3.1.zip

Server Preparations

In following examples, we use always the location: D:\ezyfox-server.

  1. Extract ezyfox-server-full-1.3.1.zip and copy the extracted files to the target location.
  2. Open the file D:\ezyfox-server\settings\ezy-settings.xml in a text editor.
  3. Add the following zones inside the <zones> tag:
<zone>
    <name>master-server</name>
    <config-file>master-server-zone-settings.xml</config-file>
    <active>true</active>
</zone>

Export External Libraries

  1. Open Git Bash and navigate to the folder master-server-startup.
  2. Run the following command: 
    mvn clean install -Denv.EZYFOX_SERVER_HOME=deploy -Pezyfox-deploy
  3. Run the ExternalLibrariesExporter tool located in free-account-server-startup/src/test/java/com/assambra/account/tools in your IDE.
  4. When prompted, enter the path: D:/ezyfox-server.

Build the Server

  1. Open the file Free-MMORPG/master-server/build.sh in the editor
  2. Remove the # from the line #export EZYFOX_SERVER_HOME=:
  3. Insert after export EZYFOX_SERVER_HOME=, the path D:/ezyfox-server.
  4. Run the following command in some command client e.g. gitbash from the root of the project (./Free-MMORPG/master-server/): 
    bash build.sh

Hint: If you encounter an error like:

cp: cannot create regular file 'D:ezyfox-server/settings/zones/': No such file or directory

Replace backslashes (\) with forward slashes (/) in your paths, depending on your operating system.

Run the Server

Navigate to your server location: D:/ezyfox-server.

  • Windows: Execute console.bat.
  • Linux: Run: 
    sh ./console.sh

For Linux as a service:

  • Start the service: 
    sh ./start-service.sh
  • Stop the service: 
    sh ./stop-service.sh
  • Restart the service: 
    sh ./restart-service.sh

(back to top)

Play the client

In your Unity project (Free-Client), double-click the Persistent scene in the folder location Assets/Free-Client/Scenes/. This is the persistent scene with all Managers/Handlers. All other scenes will automatically load additively/asynchronously when needed, along with the User Interfaces for the active scene.

To learn more about the Module-GameManager, visit the Module-GameManager wiki page.

Once everything is set up, press "Play" in the Unity Editor to start the game, provided the server setup is complete (see below).

(back to top)

Contributing

Thank you for your interest in contributing to our project! Contributions are welcome and greatly appreciated.

How to Contribute

  1. Code Contributions

    • Fork the repository on GitHub.
    • Create a new branch for your changes.
    • Implement your changes and thoroughly test them.
    • Submit a pull request to our repository.

  2. Report Bugs
    Use our GitHub issue tracking system to report bugs. Provide as much detail as possible to help us troubleshoot effectively.

  3. Feature Requests
    If you have a great idea for a new feature, create an issue on GitHub and describe your idea in detail. We'll review and discuss it.

  4. Documentation Contributions
    If you find errors or want to add to our documentation, feel free to contribute to our Wiki or submit pull requests for README updates.

(back to top)

Resources

  • For the master-server foundation, this project uses the EzyFox Server Archetype from Young Monkeys.
  • The project also uses technologies from the broader EzyFox ecosystem. Some dependencies are already included through the archetype project, while others such as GameBox and EzyData JPA were added separately as explicit project dependencies.
  • The EzyFox CSharp Client is downloaded separately and integrated into the Free-Client and Free-Server projects.
  • For the character system, this project uses UMA (Unity Multipurpose Avatar System). UMA is added separately and is not included in this repository. Please obtain it from the original source and follow its license terms.
  • For the ocean, we use the Crest Ocean System, which we consider one of the best ocean systems available for Unity. You can support the project via GitHub Sponsors.
  • For terrain generation, we use MapMagic 2, currently the free version. If you need more features, consider the bundle version or other MM2 addons to support the developer.

(back to top)

Credits

  • We use textures created by João Paulo, available at 3DTextures.me. These textures were published under the CC0 license. You can support his work via Ko-fi or Patreon.
  • Parts of this project are based on or reuse code/assets from RPG Core by Enzo. Special thanks to him for clarifying the license terms and allowing reuse within this project.

(back to top)

Special Thanks

  • A special thanks to tvd12 and the Young Monkeys / EzyFox team for fixing bugs, providing support, and helping with technical issues related to this project.

(back to top)

Third-Party Notices

This project uses, references, or depends on third-party software, frameworks, libraries, and assets.

For additional third-party license, attribution, and notice details, see THIRD_PARTY_NOTICES.md.

(back to top)

Contact

Join us on Discord.

(back to top)

About

Free-MMORPG is an open-source project designed to provide a comprehensive framework for building multiplayer online role-playing games. Leveraging cutting-edge technologies and community-driven solutions, the project includes robust server infrastructure, modular client components, and highly customizable character systems.

Topics

client server unity mmorpg ezyfox

Resources

Readme

License

MIT license
Activity

Stars

13 stars

Watchers

1 watching

Forks

5 forks
Report repository

Releases

136 tags

Packages

 
 
 

Contributors

Languages