Skip to content
/ Free-MMORPG Public

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.

License

MIT license
9 stars 3 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

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-based System
    • An entity is the base and can represent a player, effect, or building (currently, only Player is implemented)
    • Each entity on the Unity Client has a NetworkTransform component to receive position updates
    • If the Unity-Server sends a spawn or despawn command to the player (Client), the entity will be automatically added to or removed from the client entity list and instantiated or destroyed accordingly
  • 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
    • (Todo) Delete a Character
  • Character Movement
    • Server Authoritative, movement (no client side prediction, server reconciliation or entity interpolation, simple send input compute position on the server send back to client)
    • Simple but working animation based by the position the player getting from the server
  • 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 .rar 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. Create the following collections:
db.createCollection("account", { collation: { locale: 'en_US', strength: 2 } })
db.account.createIndex({ username: 1 })
db.createCollection("character", { collation: { locale: 'en_US', strength: 2 } })
db.character.createIndex({ accountId: 1 })
db.createCollection("character_location", { collation: { locale: 'en_US', strength: 2 } })
db.character_location.createIndex({ characterId: 1 })
  1. Add to the following configuration file:

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.2.9.zip

Server Preparations

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

  1. Extract ezyfox-server-full-1.2.9.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>free-master-server-zone-settings.xml</config-file>
    <active>true</active>
</zone>

Export External Libraries

  1. Open Git Bash and navigate to the folder free-account-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 Section

(back to top)

Credits

  • We use textures created by João Paulo, available at 3DTextures.me. He published these under the CC0 license. You can support him by buying him a Ko-fi or becoming a patron on Patreon.

(back to top)

Thank You

  • A special thanks to tvd12 for fixing various bugs and providing great help with other issues.

(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

9 stars

Watchers

1 watching

Forks

3 forks
Report repository

Releases

103 tags

Packages

No packages published

Contributors 3

  •  
  •  
  •  

Languages