Documentation ¶
Overview ¶
Package profile allows the username, ID, skin and username history of Minecraft profiles to be retrieved by either username or ID. It is a binding for the public Mojang API described at: http://wiki.vg/Mojang_API.
Since Mojang's API historically have been inconsistent on whether demo profiles are returned or not, to ensure consistency this package have been written never to return those.
Please note that the public Mojang API is request rate limited, so if you expect heavy usage you should cache the results. For more information on rate limits see the documentation for ErrTooManyRequests.
Example ¶
The following example shows how to retrieve and report all information about a Minecraft profile based on its username.
package main import ( "fmt" "log" "context" "github.com/PhilipBorgesen/minecraft/profile" ) func main() { ctx := context.TODO() // User to retrieve information about const username = "nergalic" // Retrieve basic information p, err := profile.Load(ctx, username) if err != nil { log.Fatalf("Failed to load profile: %s", err) } // Get case-corrected username and ID name, id := p.Name, p.ID // Load previously associated usernames hist, err := p.LoadNameHistory(ctx, false) if err != nil { log.Fatalf("Failed to load profile name history: %s", err) } // Load cape, skin and model type props, err := p.LoadProperties(ctx, false) if err != nil { log.Fatalf("Failed to load profile properties: %s", err) } // Get model type, skin and cape model, skin, cape := props.Model, props.SkinURL, props.CapeURL // If profile has no custom skin if skin == "" { skin = "<NONE>" } // If profile has no cape if cape == "" { cape = "<NONE>" } // Report information fmt.Printf("INFORMATION FOR: %32s\n", username) fmt.Println("---------------------------------------------------------") fmt.Printf("CASE-CORRECTED USERNAME: %32s\n", name) fmt.Printf("ID: %32s\n", id) fmt.Printf("PRIOR NAMES: %32s\n", fmt.Sprint(hist)) fmt.Println() fmt.Printf("SKIN MODEL: %32s\n", model) fmt.Printf("SKIN URL: %32s\n", skin) fmt.Printf("CAPE URL: %32s\n", cape) }
Output: INFORMATION FOR: nergalic --------------------------------------------------------- CASE-CORRECTED USERNAME: Nergalic ID: 087cc153c3434ff7ac497de1569affa1 PRIOR NAMES: [GeneralSezuan] SKIN MODEL: Steve SKIN URL: http://textures.minecraft.net/texture/5b40f251f7c8db60943495db6bf54353102d6cad20d2299d5f973f36b4f3677e CAPE URL: <NONE>
Index ¶
- Constants
- Variables
- type ErrMaxSizeExceeded
- type Model
- type PastName
- type Profile
- func Load(ctx context.Context, username string) (p *Profile, err error)
- func LoadAtTime(ctx context.Context, username string, t time.Time) (p *Profile, err error)
- func LoadByID(ctx context.Context, id string) (p *Profile, err error)
- func LoadMany(ctx context.Context, usernames ...string) (ps []*Profile, err error)
- func LoadWithNameHistory(ctx context.Context, id string) (p *Profile, err error)
- func LoadWithProperties(ctx context.Context, id string) (p *Profile, err error)
- type Properties
Examples ¶
Constants ¶
const LoadManyMaxSize int = 100
LoadManyMaxSize is the maximum number of profiles which may be requested at once using LoadMany. If more are requested, the request may fail with an ErrMaxSizeExceeded error.
Variables ¶
var ( ErrNoCape = errors.New("minecraft/profile: profile has no cape") ErrNoSuchProfile = errors.New("minecraft/profile: no such profile") ErrUnsetPlayerID = errors.New("minecraft/profile: player id is not set") ErrUnknownModel = errors.New("minecraft/profile: unknown model") // ErrTooManyRequests is returned if the client has exceeded its server // communication rate limit. At the time of writing, the load operations // have a shared rate limit of 600 requests per 10 minutes. // // Note that the rate limit for reading profile properties is much // stricter: For each profile, profile properties may only be requested // once per minute. ErrTooManyRequests = errors.New("minecraft/profile: request rate limit exceeded") )
Functions ¶
This section is empty.
Types ¶
type ErrMaxSizeExceeded ¶
type ErrMaxSizeExceeded struct {
Size int // Number of profiles which were requested.
}
An ErrMaxSizeExceeded error is returned when LoadMany is requested to load more than LoadManyMaxSize profiles at once.
func (ErrMaxSizeExceeded) Error ¶
func (e ErrMaxSizeExceeded) Error() string
type PastName ¶
type PastName struct { // Name is a username used by the profile in the past. Name string // Until is the time instant the profile stopped using Name as username. // Prior past usernames may be consulted to determine when this username // was taken into use. Until time.Time // contains filtered or unexported fields }
PastName represents one of a profile's past usernames. PastName values should be used as map or database keys with caution as they contain a time.Time field. For the same reasons, do not use == with PastName values; use Equal instead.
type Profile ¶
type Profile struct { // ID is the profile's universally unique identifier, which never changes. ID string // Name is the profile's currently associated username, subject to change. Name string // NameHistory is the profile's past usernames incl. when each username // stopped being used. The profile's last username is first, its original // username is last. Unless explicitly loaded, NameHistory may be nil. NameHistory []PastName // Properties contains the skin, model and cape used by the profile. // Unless explicitly loaded, Properties may be nil. Properties *Properties // contains filtered or unexported fields }
Profile represents the profile of a Minecraft user account.
func Load ¶
Load fetches the profile currently associated with username. ctx must be non-nil. If no profile currently is associated with username, Load returns ErrNoSuchProfile. If an error is returned, p will be nil.
func LoadAtTime ¶
LoadAtTime fetches the profile associated with username at the specified instant of time. ctx must be non-nil. If no profile was associated with username at the specified instant of time, LoadAtTime returns ErrNoSuchProfile. If an error is returned, p will be nil.
Example ¶
The following example shows how to retrieve a Minecraft profile based on the username it was registered under.
package main import ( "fmt" "log" "context" "time" "github.com/PhilipBorgesen/minecraft/profile" ) func main() { ctx := context.TODO() // Username the profile originally used const origUser = "GeneralSezuan" // Retrieve basic information of profile p, err := profile.LoadAtTime(ctx, origUser, time.Unix(0, 0)) if err != nil { log.Fatalf("Failed to load profile: %s", err) } fmt.Println("Current username: " + p.Name) fmt.Println(" Profile ID: " + p.ID) }
Output: Current username: Nergalic Profile ID: 087cc153c3434ff7ac497de1569affa1
func LoadByID ¶
LoadByID fetches the profile identified by id. ctx must be non-nil. If no profile is identified by id, LoadByID returns ErrNoSuchProfile. If an error is returned, p will be nil.
func LoadMany ¶
LoadMany fetches multiple profiles by their currently associated usernames. Usernames associated with no profile are ignored and absent from the returned results. Duplicate usernames are only returned once, and ps will be nil if an error occurs. ctx must be non-nil.
NB! Only a maximum of LoadManyMaxSize profiles may be fetched at once. If more are attempted loaded in the same operation, an ErrMaxSizeExceeded error is returned.
Example ¶
The following example demonstrates how to load basic information of multiple Minecraft profiles based on their currently associated usernames.
package main import ( "fmt" "log" "context" "github.com/PhilipBorgesen/minecraft/profile" ) func main() { ctx := context.TODO() // Retrieve basic information of profiles that exist ps, err := profile.LoadMany(ctx, "nergalic", "breesakana", "doesNotExist") if err != nil { log.Fatalf("Failed to load profiles: %s", err) } for _, p := range ps { fmt.Printf("%-10s %s\n", p.Name, p.ID) } }
Output: BreeSakana d9a5b542ce88442aaab38ec13e6c7773 Nergalic 087cc153c3434ff7ac497de1569affa1
func LoadWithNameHistory ¶
LoadWithNameHistory fetches the profile identified by id, incl. its name history. ctx must be non-nil. If no profile is identified by id, LoadWithNameHistory returns ErrNoSuchProfile. If an error is returned, p will be nil.
func LoadWithProperties ¶
LoadWithProperties fetches the profile identified by id, incl. its properties. ctx must be non-nil. If no profile is identified by id, LoadWithProperties returns ErrNoSuchProfile. If an error is returned, p will be nil.
NB! For each profile, profile properties may only be requested once per minute.
func (*Profile) LoadNameHistory ¶
LoadNameHistory loads and returns p.NameHistory, which contains the profile's past usernames. If force is true, p.NameHistory will be loaded anew from the Mojang servers even though it already is present. If force is false, p.NameHistory will only be loaded if nil.
ctx must be non-nil and p.ID must be set. When the name history is loaded, p.Name will also be updated if it has changed.
No matter whether the loading succeeds or not, p.NameHistory will be returned as hist, which thus only will be nil if the loading fails and p.NameHistory was nil beforehand.
A profile which was loaded by LoadWithNameHistory has p.NameHistory pre-loaded.
func (*Profile) LoadProperties ¶
LoadProperties loads and returns p.Properties, which contains the profile's skin, cape and model. If force is true, p.Properties will be loaded anew from the Mojang servers even though it already is present. If force is false, p.Properties will only be loaded if nil.
ctx must be non-nil and p.ID must be set. When properties are loaded, p.Name will also be updated if it has changed.
No matter whether the loading succeeds or not, p.Properties will be returned as ps, which thus only will be nil if the loading fails and p.Properties was nil beforehand.
A profile which was loaded by LoadWithProperties has p.Properties pre-loaded.
NB! For each profile, profile properties may only be requested once per minute.
type Properties ¶
type Properties struct { // SkinURL is an URL to the profile's custom skin texture. // If SkinURL == "", no skin texture has been set and the profile uses the // default skin for Model. SkinURL string // CapeURL is an URL to the profile's cape texture. // If CapeURL == "", no cape is associated with the profile. CapeURL string // Model is the profile's player model type. Model Model // contains filtered or unexported fields }
Properties contains additional information associated with a Profile.
func (*Properties) CapeReader ¶
func (p *Properties) CapeReader(ctx context.Context) (io.ReadCloser, error)
CapeReader is a convenience method for retrieving the cape texture at p.CapeURL. ctx must be non-nil. If p.CapeURL == "", ErrNoCape is returned as error.
It is the client's responsibility to close the ReadCloser. When an error is returned, ReadCloser is nil.
func (*Properties) SkinReader ¶
func (p *Properties) SkinReader(ctx context.Context) (io.ReadCloser, error)
SkinReader is a convenience method for retrieving the skin texture at p.SkinURL. ctx must be non-nil. If p.SkinURL == "", the default texture for p.Model will be attempted to be retrieved instead.
It is the client's responsibility to close the ReadCloser. When an error is returned, ReadCloser is nil.